Getting started
Sources
- Concepts
- Event Spec
- Extending the Spec
- Integrations
- Monitoring
- Consent
- Set up a proxy
Connections
- Integrations
- Filters
- Monitoring
- Custom Events
- Consent
Insights & Dashboards
Marketing Sources
- Integrations
Settings
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 Connections
- 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.
Of course, you can still extend the Converge Spec with your own events, properties, etc.
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.
This event should be tracked on the client.
You do not need to manually implement any of the below properties, they will be automatically tracked for all client-side events.
IP address of the user.
URL of the pageview.
URL referrer of the pageview.
Browser timezone.
Viewport size of the pageview.
The sales channel where the event occurred. For client-side events tracked through the Converge Pixel, this will always by default be “web”. More on supported sales channels can be found here.
IP address of the user.
Converge cookie ID.
User Agent of the last browser session of the user.
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.
This event should be tracked on the client.
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
Currency of the product that is being viewed, as per ISO 4217
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.
Viewed Collection
When a user views a collection detail page that includes multiple products.
This event should be tracked on the client.
Collection ID of the collection that is being viewed.
Name of the collection that is being viewed.
Description of the collection that is being viewed.
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
Currency of the product that is being viewed, as per ISO 4217
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.
Added To Cart
When a user adds a product to cart
This event should be tracked on the client.
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.
Currency of the product that is being viewed, as per ISO 4217
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.
Started Checkout
When a user starts the checkout process.
This event should be tracked on the client.
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
Currency of the cart that is being checked out, as per ISO 4217
Product ID of the item.
Variant ID of the product variant
SKU of the product and variant
Product Name of the item
Variant name of the product variant
Unit price of the item
Currency of the product, as per ISO 4217
Name of the vendor of the product.
Amount of times the item is present in the cart at checkout.
URL to the product page of the item
URL of a product image of the item
Added Payment Info
When a user adds their payment info.
This event should be tracked on the client.
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
Currency of the cart that is being checked out, as per ISO 4217
Product ID of the item.
Variant ID of the product variant
SKU of the product and variant
Product Name of the item
Variant name of the product variant
Unit price of the item
Currency of the product, as per ISO 4217
Name of the vendor of the product.
Amount of times the item is present in the cart at checkout.
URL to the product page of the item
URL of a product image of the item
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.
Country code of the user’s address according to ISO 3166.
State of the user’s address.
Zip code of the user’s address.
Placed Order
When a user places an order.
Conversion event: you should adhere to the Where To Track, Deduplication and Session Stitching guidelines.
This event should be tracked on both the client and the server.
You should pass a unique eventID so client-side and server-side copies of
the same order can be deduplicated.
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
Which alias you use depends on your exact setup and which identifiers are available both on the browser and the server in a user journey.
Learn more about session stitching and aliases here.
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.
Currency of the order, as per ISO 4217
Product ID of the item in the order.
Variant ID of the item in the order
SKU of the item in the order
Product Name of the item in the order
Variant name of the product variant
Unit price of the item in the order
Currency of the item in the order, as per ISO 4217
Name of the vendor of the item in the order.
Amount of times the item is present in the order.
URL to the product page of the item
URL of a product image of the item
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.
Country code of the user’s address according to ISO 3166.
State of the user’s address.
Zip code of the user’s address.
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. Browser Placed Order events should always be “web”.
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.
Country code of the user’s address according to ISO 3166.
State of the user’s address.
Zip code of the user’s address.
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
This event should be tracked on the client.
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.
Currency of the cart that is being checked out, as per ISO 4217
Product ID of the item.
Variant ID of the product variant
SKU of the product and variant
Product Name of the item
Variant name of the product variant
Unit price of the item
Currency of the product, as per ISO 4217
Name of the vendor of the product.
Amount of times the item is present in the cart at checkout.
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.
This event should be tracked on both the client and the server.
You should pass a unique eventID so client-side and server-side copies of
the same order can be deduplicated.
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
Which alias you use depends on your exact setup and which identifiers are available both on the browser and the server in a user journey.
Learn more about session stitching and aliases here.
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.
Currency of the subscription, as per ISO 4217
Product ID of the item in the subscription.
Variant ID of the item in the subscription
SKU of the item in the subscription
Product Name of the item in the subscription
Variant name of the item in the subscription
Unit price of the item in the subscription
Currency of the item in the subscription, as per ISO 4217
Name of the vendor of the item in the subscription.
Amount of times the item is present in the subscription.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
The sales channel where the event occurred. For client-side events tracked through the Converge Pixel, this will always by default be “web”. More on supported sales channels can be found here.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
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.
This event should be tracked on the server.
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.
Currency of the subscription, as per ISO 4217
Product ID of the item in the subscription.
Variant ID of the item in the subscription
SKU of the item in the subscription
Product Name of the item in the subscription
Variant name of the item in the subscription
Unit price of the item in the subscription
Currency of the item in the subscription, as per ISO 4217
Name of the vendor of the item in the subscription.
Amount of times the item is present in the subscription.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
The sales channel where the event occurred. Due to this event typically being server side, the sales channel type should be “offline”. More on supported sales channels can be found here.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
Placed Recurring Subscription Order
When a user places a recurring subscription order.
This event should be tracked on the server.
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.
Currency of the subscription, as per ISO 4217
Product ID of the item in the subscription.
Variant ID of the item in the subscription
SKU of the item in the subscription
Product Name of the item in the subscription
Variant name of item in the subscription
Unit price of the item in the subscription
Currency of the item in the subscription, as per ISO 4217
Name of the vendor of the item in the subscription.
Amount of times the item is present in the subscription.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
The sales channel where the event occurred. Due to this event typically being server side, the sales channel type should be “subscription_contract”. More on supported sales channels can be found here.
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.
Country code of the subscriber’s address according to ISO 3166.
State of the subscriber’s address.
Zip code of the subscriber’s address.
Useful Additional Events
Most ad platforms rely on the email 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 should be tracked on the client.
Email of the signed up user.
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.
Country code of the user’s address according to ISO 3166.
State of the user’s address.
Zip code of the user’s address.
Signed Up
When a user signs up.
This event should be tracked on the client.
Email of the signed up user.
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.
Country code of the user’s address according to ISO 3166.
State of the user’s address.
Zip code of the user’s address.
- Why the Converge Spec?
- Advantages of a strict spec
- Auto-tracking
- $page_load
- Ecommerce Events
- Viewed Product
- Viewed Collection
- Added To Cart
- Started Checkout
- Added Payment Info
- Placed Order
- Viewed Cart
- Subscription Lifecycle Events
- Started Subscription
- Cancelled Subscription
- Placed Recurring Subscription Order
- Useful Additional Events
- Logged In
- Signed Up