Skip to main content

Events Tracking

This API tracks the different user events. Events tracking is imperative to provide personalized user journeys and improve customer engagement. This also serves to measure and monitor performance of the different recommendation strategies defined for the different touchpoints.

Authentication#

You can use API keys or Requesting URLs based on your requirements & preference. Check here to choose one that suits you the best.

Request#

Request Type#

POST

Request Headers#

Request Headerx-api-key: <api_key>
Note:

You can skip sending x-api-key if you choose authentication via Requesting URL.

Endpoint#

The base URL will be provided to you at the time of onboarding.

POST <base_url>/events/track

Request Parameters#

Request parameters to be specified within key "data"

ParamTypeRequiredDescriptionMandatory for Events
mad_uuidstringyesAuto generated uuid for a user session. Should be stored in the cookie for the period of 1 year. If Integration Mode is API, set and get mad_uuid using this method. Note: The same mad uuid should be passed in the events, search and recommendations API request.All
user_idstringyes for logged in usersUnique ID associated by the merchant to the user in the site.All
urlstringyesURL of the page.All
referrerstringyes, if applicableReferrer URL from where the user was redirected to the current page.All
mediumstringyesUnique Identifier for events. Allowed Values: vue_x for website/app events, offline_data for offline events.All
sourcestringyesIndicates a unique source. Allowed Value: client name provided at time of onboarding.All
platformstringyesIndicates the platform of the event. Allowed Values: desktop, mobile, android, iosAll
namestringyesIndicates name of the event. Refer here for event names that we recommend to be tracked.All
actionstringyesIndicates action of the event. Refer here for event actions that we recommend to be tracked.All
non_interactionstringyesIndicates action triggered by interaction or otherwise. Allowed values: true, false.All
metadata -> account_idstringyesClient account ID associated with the tool.All
metadata -> regionstringyesIndicates the internal region associated with the client account. Allowed values: us-east-1, ap-southeast-1, eu-central-1All
metadata -> region_codestringyes if multi- region is supportedRegion or Locale code of the site.All
metadata -> envstringyesClient environment. Allowed values: prod, stagingAll
metadata -> currencystringyesCurrency supported by the website.To be passed in addtoCart, pageView of Product Detail Page, orderConfirmation and placeOrder events
metadata -> page_typestringyesIndicates page type. Refer here for the values of pageType for the different pages in the website.All
metadata -> module_idstringyes for some eventsIndicates the ID of the module that is rendered in recommendation.All
metadata -> strategy_idstringyes for some eventsIndicates the ID of the strategy that is rendered in recommendation.All
metadata -> module_namestringyes for some eventsIndicates the module name that is rendered in recommendation.All
metadata -> product_listarray of JSON objectsyes for some events/page typesProduct list that is under view.All
metadata -> referrer_productJSON objectyes for some events/page typesSource Product for which the recommendation was rendered.To be passed in recommendedProductView
metadata -> pos_of_reconumberyes for some eventsPosition of the product that was clicked in the recommendation.recommendedProductView
metadata -> recos_servedstringyes for some eventsNumber of recommendations served in the page.recommendationView
metadata -> template_typestringyes for some eventsIndicates type of template. Allowed Values: simple-carousel, carousel, simple-grid.All
metadata -> module_behaviourstringyes for some eventsIndicates how the recommendation is rendered. Allowed values: inline, popupAll
metadata -> categorystringyes for some page typesIndicates the category of the page for Product Listing Page.All
metadata -> order_byJSON objectyes, if applicableIndicates the sort order applied for the Product Listing Page. Sort section describes this in detail.All
metadata -> filtersarray of JSON objectsyes, if applicableIndicates the filters applied for the Product Listing Page. Filters section describes this in detail.All
metadata -> order_idstringyes for some eventsIndicates the ID of the order placed.orderConfirmation and placeOrder
_journey_metadata -> audience_idstringyesIndicates the audience ID for which the recommendation is rendered. Read from Recommendation API response.All
_journey_metadata -> page_idstringyesIndicates the page ID where the recommendation is rendered. Read from Recommendation API response.All
_journey_metadata -> experience_idstringyesIndicates the experience ID for which the recommendation is rendered. Read from Recommendation API response.All
_journey_metadata -> journey_idstringyesIndicates the journey ID for which the recommendation is rendered. Read from Recommendation API response.All

Note: Refer here for the events that are required to be tracked.

Product Detail Object Parameters#

ParamTypeRequiredDescription
product_idstringyesFor event: recommendationView - Indicates the unique product identifier of the product for which recommendations are viewed. For event: recommendedProductView - Indicates the unique product identifier of the product which was clicked on.
pricestringyesThe price of the product in reference.
quantityintegernoThe no. of quantity selected for the product in reference.

Response#

Response is a JSON indicating success/failure of the API call

Response Status Code#

Indicates any response to the event request. For the different response codes we return, please refer the table below.

Response CodeDescription
200Request successfully processed.
401Authorization has been denied for this request.
500Unhandled application errors

Example 1 - Page View Event for Home Page#

Publish Page View event when Home Page loads

Request#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e156",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38bc5",
"user_id": "user_abc",
"url": "https://example-site.com/",
"referrer": "",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "pageView",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "home"
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 2 - Page View Event for Product Description Page#

Publish Page Vuew event when Product Description Page loads

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e156",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38fc6",
"user_id": "user_abc",
"url": "https://example-site.com/product/beige-fanny-pack-33941",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "pageView",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "pdp",
"product_list": [
{
"product_id": "2019000100030423",
"price": "79.00"
}
]
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 3 - Add To Cart Event from Product Description Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e167",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38fc9",
"user_id": "user_abc",
"url": "https://example-site.com/product/beige-fanny-pack-33941",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "addToCart",
"action": "click",
"non_interaction": "false",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "pdp",
"product_list": [
{
"product_id": "2019000100030423",
"price": "79.00"
}
]
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 4 - Order Confirmation Event#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e167",
"mad_uuid": "4d3be7e9-0b87-41b9-94c7-b5da57cde234",
"user_id": "user_abc",
"url": "https://example-site.com/checkout-finished?orderId=378829558",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "orderConfirmation",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "86a4c9b0-c27f-4a2d-ba7e-f53848da8894",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "oc",
"order_id": "378829558",
"product_list": [
{
"price": "19",
"quantity": "1",
"product_id": "2019000100027007"
},
{
"price": "99",
"quantity": "1",
"product_id": "2019000100022951"
}
]
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "1600",
"experience_id": "374",
"journey_id": "450"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 5 - Recommendation View Event from a Product Description Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e167",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38cdf",
"user_id": "user_abc",
"url": "https://example-site.com/product/beige-fanny-pack-33941",
"referrer": "",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "recommendationView",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14690",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "pdp",
"product_list": [
{
"product_id": "2019000100030423",
"price": "79.00"
}
],
"module_id": "1645",
"module_name": "Similar Module",
"module_behaviour": "inline",
"template_type": "simple-carousel",
"recos_served": 16
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 6 - Recommended Product View from a Product Description Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e167",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38c90",
"user_id": "user_abc",
"url": "https://example-site.com/product/beige-fanny-pack-33941",
"referrer": "",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "recommendedProductView",
"action": "click",
"non_interaction": "false",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14589",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "pdp",
"product_list": [
{
"product_id": "2018000100019623",
"price": 39
}
],
"module_id": "1645",
"module_name": "Similar Module",
"template_type": "simple-carousel",
"module_behaviour": "inline",
"strategy_id": "1578",
"referrer_product": {
"product_id": "2019000100030423"
},
"pos_of_reco": 1
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 7 - Swipe Event from a Carousel on Product Description Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e167",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38cb7",
"user_id": "user_abc",
"url": "https://example-site.com/product/blue-geometric-print-bohemian-a-line-dress-39848",
"referrer": "https://example-site.com/shop/dresses-12",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "rightSwipe",
"action": "click",
"non_interaction": "false",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14390",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"page_type": "pdp",
"product_list": [
{
"product_id": "2021000100037146",
"price": "39.00"
}
],
"module_id": "1645",
"module_name": "Similar Module",
"template_type": "simple-carousel",
"module_behaviour": "inline"
},
"_journey_metadata": {
"page_id": "2132",
"journey_id": "855",
"experience_id": "1719",
"audience_id": "1"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 8 - Page View Event from a Personalized Search/Listing Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e156",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38fc6",
"user_id": "user_abc",
"url": "https://example-site.com/collections/shoes",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "pageView",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"category": "Dresses",
"order_by": {
"field": "relevance",
"order": "desc"
},
"filters": [
{
"field": "available",
"type": "exact",
"value": "true"
}
],
"page_type": "cat"
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 9 - Recommendation View Event from a Personalized Search/Listing Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e156",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38fc6",
"user_id": "user_abc",
"url": "https://example-site.com/collections/shoes",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "recommendationView",
"action": "pageView",
"non_interaction": "true",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"category": "Dresses",
"order_by": {
"field": "relevance",
"order": "desc"
},
"filters": [
{
"field": "available",
"type": "exact",
"value": "true"
}
],
"page_type": "cat",
"module_id": "1645",
"module_name": "Personalized Listing",
"module_behaviour": "inline",
"template_type": "simple-grid",
"recos_served": 50
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);

Example 10 - Recommended Product View Event from a Personalized Search/Listing Page#

var data = {
"data": {
"api_key": "9ed6bd6a23db7dd422893e156",
"mad_uuid": "2921651f-8ed9-4480-8c40-1021ddb38fc6",
"user_id": "user_abc",
"url": "https://example-site.com/collections/shoes",
"referrer": "https://example-site.com",
"medium": "vue_x",
"source": "client_name",
"platform": "desktop",
"name": "recommendedProductView",
"action": "click",
"non_interaction": "false",
"metadata": {
"account_id": "c17c8af3-e92f-42e7-ba3a-5b316bc14679",
"region": "us-east-1",
"env": "prod",
"currency": "USD",
"category": "Dresses",
"pos_of_reco": 1,
"order_by": {
"field": "relevance",
"order": "desc"
},
"filters": [
{
"field": "available",
"type": "exact",
"value": "true"
}
],
"page_type": "cat",
"product_list": [
{
"product_id": "2018000100019623",
"price": 39
}
],
"module_id": "1645",
"module_name": "Personalized Listing",
"module_behaviour": "inline",
"template_type": "simple-grid",
"recos_served": 50
},
"_journey_metadata": {
"audience_id": "1",
"page_id": "2132",
"experience_id": "1719",
"journey_id": "855"
}
}
};
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "{{base_url}}/events/track");
xhr.setRequestHeader("content-Type", "application/json");
xhr.send(data);