- Book a demo
- Community
Integrations
- Workspace
Ad Platforms
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.
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.
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.
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
Currency of the product that is being viewed, as per ISO 4217
Name of the vendor of the product 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.
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 .
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.
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.
cvg({
method: "track",
eventName: "Started Checkout",
properties: {
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
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",
},
],
},
});
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.
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.
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.
cvg({
method: "track",
eventName: "Added Payment Info",
properties: {
total_price: 42,
total_tax: 3.5,--
total_shipping: 2.4,
currency: "USD",
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",
},
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 and Deduplication 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.
Order ID.
Total value of the order with tax and shipping.
Total tax of the order.
Total shipping cost of 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
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.
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.
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.
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",
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.
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.
cvg({
method: "track",
eventName: "Viewed Cart",
properties: {
total_price: 42,
total_tax: 3.5,
total_shipping: 2.4,
currency: "USD",
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 for companies who operate on subscriptions.
Started Subscription
When a user starts a subscription.
Conversion event: you should adhere to the Where To Track 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.
Total value of the subscription with tax and shipping.
Total tax of the subscription.
Total shipping cost of 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.
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.
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",
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"],
});
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.
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.
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.
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",
},
],
"$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",
},
"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.
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.
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.
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",
},
],
"$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",
},
"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"],
}
)