Tracking Events

Use converlay.track(eventName, properties) to send events. The SDK automatically enriches each event with client ID, session, UTMs, click IDs, and consent state.

API signature

track() signature

converlay.track('event_name', {
  ecommerce: {
    transaction_id: 'ORD-123',
    value: 99.99,
    currency: 'USD',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Classic Tee',
        price: 29.99,
        quantity: 2,
      },
    ],
  },
  userData: {
    email: 'customer@example.com',
  },
  pageType: 'product',
})

Standard event names

Use these event names for automatic mapping to GA4, Meta, and TikTok event types:

Event name	When to fire
`page_view`	Page load or client-side navigation
`view_item`	Product detail page
`view_item_list`	Collection or search results page
`add_to_cart`	Item added to cart
`remove_from_cart`	Item removed from cart
`search`	Search query submitted
`begin_checkout`	Checkout started
`add_payment_info`	Payment info entered
`add_shipping_info`	Shipping info entered
`purchase`	Order completed

Custom events

You can use any string as an event name. Custom events will be forwarded as-is to destinations that support them.

TrackProperties fields

Field	Type	Description
`ecommerce`	`EcommerceData`	Transaction and item data
`userData`	`UserData`	Customer PII for enhanced matching (hashed server-side)
`pageType`	`string`	Page type label (e.g., "product", "collection", "cart")
`[key: string]`	`unknown`	Any additional custom properties

Examples

View item

typescript

converlay.track('view_item', {
  ecommerce: {
    items: [{
      item_id: 'SKU-001',
      item_name: 'Classic Tee',
      item_variant: 'Blue / Large',
      price: 29.99,
      quantity: 1,
    }],
  },
})

Add to cart

typescript

converlay.track('add_to_cart', {
  ecommerce: {
    value: 29.99,
    currency: 'USD',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Classic Tee',
      price: 29.99,
      quantity: 1,
    }],
  },
})

Purchase

typescript

converlay.track('purchase', {
  ecommerce: {
    transaction_id: 'ORD-5678',
    value: 129.99,
    currency: 'USD',
    items: [
      { item_id: 'SKU-001', item_name: 'Classic Tee', price: 29.99, quantity: 2 },
      { item_id: 'SKU-042', item_name: 'Hoodie', price: 70.01, quantity: 1 },
    ],
  },
  userData: {
    email: 'customer@example.com',
    phone: '+15551234567',
    firstName: 'Jane',
    lastName: 'Doe',
  },
})

Previous← Schnellstart NextBenutzeridentifikation →