Sources
Event Spec
Why the Converge Spec?
Most CDPs are not very strict about which events you track, where you track them (client or server) and with which properties. This usually leads to problems with destinations downstream as each destination does have very specific integration requirements to operate optimally.Advantages of a strict spec
Converge, therefore works with a strict Converge Event Spec. Because we have a semantic understanding of what you are tracking, we can:- Automatically map your source events to destinations in an optimal way through our Destinations
- Surface your meaningful analytics through our Attribution product.
- Monitor and flag when you are wrongly tracking events or properties negatively affecting your destinations or analytics through Source Monitoring.
Auto-tracking
These events, event properties, profile properties and aliases will be auto-tracked by the Converge Pixel.$page_load
When a user views a page.Where To Track
Where To Track
This event should be tracked on the client.
Code Example
Code Example
You do not need to manually implement any of the below properties, they will be automatically tracked for all client-side events.
Auto-tracked Event Properties
Auto-tracked Event Properties
IP address of the user.
URL of the pageview.
URL referrer of the pageview.
Browser timezone.
Viewport size of the pageview.
Auto-tracked Profile Properties
Auto-tracked Profile Properties
Auto-tracked Aliases
Auto-tracked Aliases
urn:cookie:{cookie_id}
Alias based on the Converge cookie ID.
Ecommerce Events
These events and properties should be passed for Ecommerce brands. All of these events will contain additional prepopulated properties through auto-tracking.Viewed Product
When a user views a product detail page.Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Product ID of the item that is being viewed.
Variant ID of the product variant that is being viewed
SKU of the product and variant that is being viewed
Product Name of the item that is being viewed
Variant name of the product variant that is being viewed
Unit price of the item that is being viewed
Name of the vendor of the product that is being viewed.
URL to the product page of the item that is being viewed.
URL of a product image of the item that is being viewed.
Code Example
Code Example
Viewed Collection
When a user views a collection detail page that includes multiple products.Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Code Example
Code Example
Added To Cart
When a user adds a product to cartWhere To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Product ID of the item that is being added to cart.
Variant ID of the product variant that is being added to cart.
SKU of the product and variant that is being added to cart.
Product Name of the item that is being added to cart.
Variant name of the product variant that is being added to cart.
Unit price of the item that is being added to cart.
Amount of times the item is being added to cart.
Name of the vendor of the product that is being added to cart.
URL to the product page of the item that is being added to cart.
URL of a product image of the product that is being added to cart.
Code Example
Code Example
Started Checkout
When a user starts the checkout process. This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate aliases
Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Total value of the cart at checkout with tax and shipping.
Total tax of the cart at checkout.
Total shipping cost of the cart at checkout.
Total discount of the cart at checkout.
The coupon or list of coupons used at checkout
Code Example
Code Example
Added Payment Info
When a user adds their payment info. This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate aliases
Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Total value of the cart at checkout with tax and shipping.
Total tax of the cart at checkout.
Total shipping cost of the cart at checkout.
Total discount of the cart at checkout.
The coupon or list of coupons used at checkout
Profile Properties
Profile Properties
Email Address of the user.
Phone Number of the user including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the user’s address.
State of the user’s address.
Zip code of the user’s address.
Code Example
Code Example
Placed Order
When a user places an order.Conversion event: you should adhere to the Where To Track,
Deduplication and Session Stitching guidelines.
Where To Track
Where To Track
This event should be tracked on both the client and the server.
Deduplication
Deduplication
You should pass a unique
eventID so client-side and server-side copies of
the same order can be deduplicated.Session Stitching
Session Stitching
You should make sure that the conversion can be stitched to the corresponding website session by including the right set of aliases on this event and corresponding web events.Common aliases are:
- Email:
urn:email:john.smith@apple.com - Checkout Token:
urn:checkout_token:xyz_123 - Customer ID:
urn:customer_id:123456
Event Properties
Event Properties
Order ID.
Total value of the order with tax and shipping.
Total tax of the order.
Total shipping cost of the order.
Total discount on the order.
The coupon or list of coupons used in the order.
Whether this is a new customer order.
The sales channel of the event. If no sales channel type is provided then Converge fallback to “web”. More on supported sales channels values can be found here. The sales channel type provided entirely depends on the context of the event, integration, and where the event originates from. Client-side Placed Order events should always be “web”.
The URL of the page where the event occurred. This will be automatically tracked for all client-side events.
Profile Properties
Profile Properties
Some fields are required for both the Event Properties and the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.
Email Address of the user.
Phone Number of the user including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the user’s address.
State of the user’s address.
Zip code of the user’s address.
Code Example
Code Example
If you track conversions both server-side and client-side, you should make sure you use the
"forward" method for the client-side event.
See the client-side code example.Make sure you include the same eventID on the client-side and server-side event.Note that client-side calls use camelCase (e.g.
eventName) and server-side calls use snake_case (e.g. event_name).Viewed Cart
When a user views their cart.This is an optional event
Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
Total value of the cart with tax and shipping.
Total tax of the cart.
Total shipping cost of the cart.
Total discount of the cart.
The coupon or list of coupons used in the cart.
Code Example
Code Example
Subscription Lifecycle Events
These events and properties should be passed by companies who operate on subscriptions.Started Subscription
When a user starts a subscription.Conversion event: you should adhere to the Where To Track, Deduplication and Session Stitching guidelines.
Where To Track
Where To Track
This event should be tracked on both the client and the server.
Deduplication
Deduplication
You should pass a unique
eventID so client-side and server-side copies of
the same order can be deduplicated.Session Stitching
Session Stitching
You should make sure that the conversion can be stitched to the corresponding website session by including the right set of aliases on this event and corresponding web events.Common aliases are:
- Email:
urn:email:john.smith@apple.com - Checkout Token:
urn:checkout_token:xyz_123 - Customer ID:
urn:customer_id:123456
Event Properties
Event Properties
Total value of the subscription with tax and shipping.
Total tax of the subscription.
Total shipping cost of the subscription.
Total discount on the subscription.
The coupon or list of coupons used in the subscription.
Profile Properties
Profile Properties
Some fields are required for both the Event Properties and the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.
Email Address of the subscriber.
Phone Number of the subscriber including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the subscriber’s address.
State of the subscriber’s address.
Zip code of the subscriber’s address.
Code Example
Code Example
If you track conversions both server-side and client-side, you should make sure you use the
"forward" method for the client-side event.
See the client-side code example.Cancelled Subscription
When a user cancels a subscription.Where To Track
Where To Track
This event should be tracked on the server.
Event Properties
Event Properties
Total value of the subscription with tax and shipping.
Total tax of the subscription.
Total shipping cost of the subscription.
Total discount on the subscription.
The coupon or list of coupons used in the subscription.
Profile Properties
Profile Properties
Some fields are required for both the Event Properties and the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.
Email Address of the subscriber.
Phone Number of the subscriber including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the subscriber’s address.
State of the subscriber’s address.
Zip code of the subscriber’s address.
Code Example
Code Example
Placed Recurring Subscription Order
When a user places a recurring subscription order.Where To Track
Where To Track
This event should be tracked on the server.
Event Properties
Event Properties
Total value of the subscription with tax and shipping.
Total tax of the subscription.
Total shipping cost of the subscription.
Total discount on the subscription.
The coupon or list of coupons used in the subscription.
Profile Properties
Profile Properties
Some fields are required for both the Event Properties and the Profile Properties. The reason is that Event Properties are static and Profile Properties are dynamic. A customer might move address between two orders for example.
Email Address of the subscriber.
Phone Number of the subscriber including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the subscriber’s address.
State of the subscriber’s address.
Zip code of the subscriber’s address.
Code Example
Code Example
Useful Additional Events
Most ad platforms rely on theemail parameter being available on customer events.
For that reason, you will want to capture events that pick up this parameter.
Logged In
When a user logs in. This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate aliases
Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
This event does not require any event properties.
Profile Properties
Profile Properties
Email Address of the user.
Phone Number of the user including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the user’s address.
State of the user’s address.
Zip code of the user’s address.
Code Example
Code Example
Signed Up
When a user signs up. This event typically is used for stitching website sessions to server-side orders, make sure to add appropriate aliases
Where To Track
Where To Track
This event should be tracked on the client.
Event Properties
Event Properties
This event does not require any event properties.
Profile Properties
Profile Properties
Email Address of the user.
Phone Number of the user including the
+ sign and country code. For example: "+1 (917) 123-4567" or "+3295123456".City of the user’s address.
State of the user’s address.
Zip code of the user’s address.
Code Example
Code Example