Event Tracking

Learn how to track events using the Voltage Schema tracker.

Basic Usage

import { createAnalyticsTracker } from 'voltage-schema';
import { AnalyticsTracker, TrackerEvents, trackingConfig } from './__analytics_generated__/analytics';

const tracker = createAnalyticsTracker<TrackerEvents>(trackingConfig, {
  onEventTracked: (eventName, { properties, groups, meta }) => {
    // Send to your analytics service (e.g., Amplitude, Segment, PostHog)
  }
});

// Track an event
tracker.track('page_view', {
  "Page Name": 'Home'
});

Type Safety

The tracker provides full type safety for:

• Event names
• Event properties
• Property types
• Required vs optional properties

Additionally, properties can be a function or a promise that resolves to the expected type.

// ✅ Valid event tracking
tracker.track('page_view', {
  "Page Name": 'Home'
});

// ✅ Valid function resolving to type
tracker.track('page_view', {
  "Page Name": () => 'Home'
});

// ✅ Valid promise resolving to type
tracker.track('page_view', {
  "Page Name": new Promise((resolve) => resolve('Home'))
});

// ❌ TypeScript error: Invalid event name
tracker.track('invalid_event', {
  "Page Name": 'Home'
});

// ❌ TypeScript error: Missing required property
tracker.track('page_view', {});

// ❌ TypeScript error: Invalid property type
tracker.track('page_view', {
  "Page Name": 123
});

Working with Analytics Services

The tracker acts as a type-safe gate check before sending events to your analytics service:

import amplitude from 'amplitude-js';

const tracker = createAnalyticsTracker<TrackerEvents>(trackingConfig, {
  onEventTracked: (eventName, { properties, groups, meta }) => {
    // Send to Amplitude
    amplitude.getInstance().logEvent(eventName, {
      ...properties,
      ...groups.User
    });
  }
});

You can use any analytics service that supports event-based tracking:

• Amplitude
• Mixpanel
• Segment
• PostHog
• Custom analytics backends