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',
},
})