Getting started
Implementation
Sources
- Concepts
- Event Spec
- Extending the Spec
- Integrations
- Monitoring
- Consent
- Set up a proxy
- Tracking snippets
- GDPR Removal Request
Destinations
- Overview
- Integrations
- Filters
- Monitoring
- Event Mapping
- Consent
Data Warehouse
- Overview
- Integrations
Attribution
Insights & Dashboards
Marketing Sources
- Overview
- Integrations
Data Management
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.
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.
cvg({ method: "track", eventName: "$page_load" });
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.
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
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.
cvg({
method: "track",
eventName: "Viewed Product",
properties: {
product_id: "123456",
variant_id: "78910", // if available
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla", // if available
price: 42,
currency: "USD",
vendor: "My Store",
},
});
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
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.
cvg({
method: "track",
eventName: "Viewed Collection",
properties: {
id: "123456", // Collection ID
name: "My Collection Name",
description: "My Collection Description",
items: [
{
product_id: "123456",
variant_id: "78910", // if available
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla", // if available
price: 42,
currency: "USD",
vendor: "My Store",
},
],
},
});
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.
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.
cvg({
method: "track",
eventName: "Added To Cart",
properties: {
product_id: "123456",
variant_id: "78910",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
});
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
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
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
cvg({
method: "track",
eventName: "Started Checkout",
properties: {
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
coupon: 'COUPON123',
items: [
// Notice that this is a list of items
{
product_id: "123456",
variant_id: "78910",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
],
},
aliases: ["urn:cart_token:xyz123"]
});
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
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
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.
State of the user’s address.
Zip code of the user’s address.
cvg({
method: "track",
eventName: "Added Payment Info",
properties: {
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
coupon: 'COUPON123',
items: [
{
product_id: "123456",
variant_id: "78910",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
],
},
profileProperties: {
// Pass if available
$email: "john.smith@apple.com",
$phone_number: "+199999999",
$city: "San Francisco",
$country_code: "US",
$state: "California",
$zip_code: "94103",
},
// important, this will be used for stitching backend orders to website sessions
aliases: ["urn:email:john.smith@apple.com"],
});
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.
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
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
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.
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.
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).
cvg({
method: "forward",
eventName: "Placed Order",
eventID: "order-1", // used for deduplicating, should be unique
properties: {
id: "order-1",
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
coupon: 'COUPON123',
items: [
{
product_id: "123456",
variant_id: "654321",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
],
},
profileProperties: {
// Pass if available
$email: "john.smith@apple.com",
$phone_number: "+199999999",
$city: "San Francisco",
$country_code: "US",
$state: "California",
$zip_code: "94103",
},
aliases: ["urn:email:john.smith@apple.com"],
});
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.
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
Name of the vendor of the product.
Amount of times the item is present in the cart at checkout.
cvg({
method: "track",
eventName: "Viewed Cart",
properties: {
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
coupon: 'COUPON123',
items: [
// Notice that this is a list of items
{
product_id: "123456",
variant_id: "78910",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
],
},
});
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.
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
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.
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.
cvg({
method: "forward",
eventName: "Started Subscription",
eventID: "order-1", // should be the subscription id or order id of the first purchase
properties: {
id: "order-1",
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
coupon: 'COUPON123',
items: [
{
product_id: "123456",
variant_id: "654321",
sku: "MY_SKU",
name: "My Product",
variant_name: "Vanilla",
price: 42,
currency: "USD",
quantity: 1,
vendor: "My Store",
},
],
},
profileProperties: {
// Pass if available
$email: "john.smith@apple.com",
$phone_number: "+199999999",
$city: "San Francisco",
$country_code: "US",
$state: "California",
$zip_code: "94103",
},
// important, this will be used for stitching backend orders to website sessions
aliases: ["urn:email:john.smith@apple.com"],
});
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.
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
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.
State of the subscriber’s address.
Zip code of the subscriber’s address.
resp = requests.post(
"{YOUR_POSTBACK_ENDPOINT}",
json=
{
"event_name": "Cancelled Subscription",
"properties": {
"id": "4001920", # the subscription id
"total_price": 42,
"total_tax": 3.5,
"total_shipping": 2.4,
"currency": "USD",
"items": [
{
"product_id": "123456",
"variant_id": "654321", # important for Shopify stores
"sku": "MY_SKU",
"name": "My Product",
"variant_name": "Vanilla",
"price": 42,
"currency": "USD",
"quantity": 1,
"vendor": "My Store",
},
],
"$sales_channel_type": "offline",
},
"profile_properties": {
# Pass as many as possible
"$first_name": "John",
"$last_name": "Smith",
"$email": "john.smith@apple.com",
"$phone_number": "+199999999",
"$city": "San Francisco",
"$country_code": "US",
"$state": "California",
"$zip_code": "94103",
},
"aliases": ["urn:email:john.smith@apple.com"],
}
)
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.
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
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.
State of the subscriber’s address.
Zip code of the subscriber’s address.
resp = requests.post(
"{YOUR_POSTBACK_ENDPOINT}",
json=
{
"event_name": "Placed Recurring Subscription Order",
"properties": {
"id": "4001920", # the subscription id
"total_price": 42,
"total_tax": 3.5,
"total_shipping": 2.4,
"currency": "USD",
"items": [
{
"product_id": "123456",
"variant_id": "654321", # important for Shopify stores
"sku": "MY_SKU",
"name": "My Product",
"variant_name": "Vanilla",
"price": 42,
"currency": "USD",
"quantity": 1,
"vendor": "My Store",
},
],
"$sales_channel_type": "subscription_contract",
},
"profile_properties": {
# Pass as many as possible
"$first_name": "John",
"$last_name": "Smith",
"$email": "john.smith@apple.com",
"$phone_number": "+199999999",
"$city": "San Francisco",
"$country_code": "US",
"$state": "California",
"$zip_code": "94103",
},
"aliases": ["urn:email:john.smith@apple.com"],
}
)
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.
This event does not require any event 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.
cvg({
method: "track",
eventName: "Logged In",
profileProperties: {
$email: "john.smith@apple.com",
$phone_number: "+199999999",
$city: "San Francisco",
$country_code: "US",
$state: "California",
$zip_code: "94103",
},
// important, this will be used for stitching backend orders to website sessions
aliases: ["urn:email:john.smith@apple.com"],
});
Signed Up
When a user signs up.
This event should be tracked on the client.
This event does not require any event 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.
cvg({
method: "track",
eventName: "Signed Up",
profileProperties: {
$email: "john.smith@apple.com",
$phone_number: "+199999999",
$city: "San Francisco",
$country_code: "US",
$state: "California",
$zip_code: "94103",
},
// important, this will be used for stitching backend orders to website sessions
aliases: ["urn:email:john.smith@apple.com"],
});
- 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