SDK

Events & payloads

EventPayload shape, enrichment, standard events, and validation rules.

AI brief: EventPayload: event_id?, value?, currency?, content_ids?, content_type?, num_items?, properties?. Standard: page_view, identify, purchase, lead. Autocapture adds scroll_depth, click, form_*, engagement_time. snake_case event names.

typescript

type EventPayload = {
  event_id?: string;
  value?: number;
  currency?: string;       // ISO 4217 — required with value for purchase
  content_ids?: string[];
  content_type?: string;   // product | subscription
  num_items?: number;
  properties?: Record<string, unknown>;
};

Automatic enrichment

Every event includes server-side and client context: anonymous_id, page (url, path, referrer, title), context.user_agent, context.locale, click IDs, fingerprint hash, consent flags, and inbound_link_id when applicable.

Standard event names

Event	When	Required fields
page_view	Route change / universal script	—
identify	After identify()	email and/or user_id
purchase	Checkout success	value + currency
lead	High-intent CTA	properties recommended
add_to_cart	Cart actions	value optional
view_content	Product/pricing views	content_ids optional

ecommerce.ts

tracker.track('add_to_cart', {
  value: 49,
  currency: 'EUR',
  content_ids: ['sku_pro'],
  num_items: 1,
  properties: { list: 'pricing_page' },
});

tracker.track('purchase', {
  value: 297,
  currency: 'USD',
  content_ids: ['sku_starter'],
  properties: {
    transaction_id: 'txn_9f3a',
    payment_provider: 'stripe',
  },
});

CAPI match quality

Pass the same event_id to Meta Pixel / Google tag as tracker.track() returns. Include value, currency, and email (via prior identify) on purchase events.

Naming convention

Use snake_case and stable names. Renaming events breaks funnel reports and destination mappings. Prefer new events over renaming old ones.