Docs

Unbxd Analytics

Unbxd Analytics is a simple tracking algorithm that can be easily implemented on your ecommerce store for tracking visitor events.

What are Events?

The actions a visitor takes on your ecommerce store are known as Events. Following are the different events we track on your online store:

  • Visitor
  • Widget Impressions
  • Product Clicks
  • Add to Cart
  • Orders

When a visitor browses through your store, the integrated trackers log everything visitors do, the products they visit, orders, even the various store properties they interact with. We take that information, analyze it, and assemble a detailed profile of the visitor. We know their browsing patterns, preferences and can even determine your susceptibility to merchandising campaigns. The trackers are unique tracking codes that must be configured onto the store properties that yield an interaction. We call this interaction as an "event", for example, on the "Add to Cart" button.

The visitor profiles helps fetch relevant and personalized products as recommendations for your visitors. It also helps in generating detailed reports.

For Unbxd Recommendations to function correctly on your site, Unbxd Analytics must be configured before integrating the widgets.

Integrating Analytics

Integrating Unbxd Analytics would be your next step after uploading your Product Feed. Analytics integration is simple 2-step process which involves:

  1. Inserting a JavaScript code snippet.
  2. Inserting event trackers.

1. Inserting the JavaScript snippet

Your first step is to insert a JavaScript code snippet in the <html> header section of all pages of your store. This JavaScript code acts as an event listener which identifies event information tracked through each tracker codeand makes API calls on their behalf.

JavaScript code

<script type="text/javascript">  
  /* * * CONFIGURATION * * */
  var UnbxdSiteName = "<Site Key>";
  /* * * DON'T EDIT BELOW THIS LINE * * */
  (function() {
  var ubx = document.createElement('script'); ubx.type = 'text/javascript'; ubx.async = true;
  ubx.src = '//d21gpk1vhmjuf5.cloudfront.net/unbxdAnalytics.js';
  (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(ubx);
  })();
</script>  
  • Site Key: Specifies the Site Key of your site. To access your Keys, you need to create an account with Unbxd Recommendations.

If you have not yet registered, you can sign up with Unbxd Recommendations here.

Important:

The JavaScript code is loaded asynchronously which means, it will not affect the load time of your webpages.

2. Tracking Events

Once you have successfully added the JavaScript code snippet, you next step is to insert or configure event trackers across your website and in certain site properties to track every event on your website. There are two ways through which you can track visitor events:

  1. HTML metatags
  2. Restful APIs

You need to track events:

  • across the site
  • on recommendation widgets
  • on widget impressions

Note

The JavaScript code automatically tracks visitors and identifies their repeat visits. So, you do not need to track visitor events.

2.1 Tracking using HTML attributes

Unbxd provides dedicated HTML attributes to be inserted on certain site properties that results in an event and help Unbxd obtain the required event information. This information is stored until the visitor's browser cookies are cleared.

2.1.a Tracking across the site

The following tags must be inserted across your site:

Product Clicks

Tracking product clicks of visitors helps our search engine to understand their preferences over other products on the listing page. This information is used to compute popular products and render relevant and personalized results . It needs to be tracked in case of search and navigation pages. It is also integrated if customer is using the recommendation widgets.

The following attributes are inserted within the product <div>(product thumbnail) or within the <li> html tags that displays lists of products on the search results page or category page:

<li unbxdattr = "product" unbxdparam_sku = "SKU001" unbxdparam_prank = "1" unbxdparam_requestId = "607a0bbf-179a-44af-8bdd-e58fef7fc5f3" ></li>  

Or

<div unbxdattr = "product" unbxdparam_sku = "SKU001" unbxdparam_prank = "1" unbxdparam_requestId = "607a0bbf-179a-44af-8bdd-e58fef7fc5f3" ></div>  
  • unbxdattr: Specifies the type of event getting captured. For product clicks, the value is "product"
  • unbxdparam_sku: uniqueId of the product as defined in the feed schema.
  • Unbxdparam_prank: The rank at which the SKU appears among the search results for a query in the grid/list. The first product will have the value of this parameter as “1”, while the second product will have the value as “2” and sequentially even other products will be ranked accordingly
  • unbxdparam_requestId: The unbxd request id returned in the search/category page api call response.

In case customer is using Unbxd Recommendations, an attribute unbxdParam_boxType has to be added within the tag with value for corresponding recommendation widget.

Example for Recommended for You recommendation widget:

<li unbxdattr = "product" unbxdparam_sku = "SKU001" unbxdparam_prank = "1"  
unbxdParam_boxType = "RECOMMENDED_FOR_YOU" unbxdparam_requestId = "607a0bbf-179a-44af-8bdd-e58fef7fc5f3" ></li>  
  • unbxdattr: Specifies the type of event getting captured. For product clicks, the value is "product"
  • unbxdparam_sku: This is the ‘uniqueId’ of the product as defined in the feed. For more information, refer the feed documentation.

    Note: Even if your products have variants, please do not pass the variant id here. We capture the click on the rolled-up entity and not on the individual variant on the search results page.

  • unbxdparam_prank: The rank at which the SKU appears within the recommendation widget. The first product will have the value of this parameter as “1”, while the second product will have the value as “2” and sequentially even other products will be ranked accordingly

  • unbxdparam_requestId: The unbxd request id returned in the recommendations api call response.
  • unbxdParam_boxType: Specifies the type of recommendation widget. For different permissible values, refer the table below.
Widget TypeBox Type Value
Recommended For YouRECOMMENDED_FOR_YOU
Recently Viewed RECENTLY_VIEWED
More Like These MORE_LIKE_THESE
Viewed also Viewed ALSO_VIEWED
Bought also Bought ALSO_BOUGHT
Cart Recommendations CART_RECOMMEND
HomePage Top Sellers TOP_SELLERS
Category Top Sellers CATEGORY_TOP_SELLERS
Brand Top Sellers BRAND_TOP_SELLERS
Add to Carts

The following attributes need to be inserted within the HTML element of the Add to Cart button on your site.

<input unbxdattr = "AddToCart" unbxdparam_sku = "SKU001" unbxdparam_variant = "VAR001" unbxdparam_qty = "2" unbxdparam_requestId = "607a0bbf-179a-44af-8bdd-e58fef7fc5f3">  
  • unbxdattr: Specifies the type of event getting captured. For product clicks, the value is "AddToCart".
  • unbxdparam_sku: UniqueId of the product as defined in the feed schema.
  • unbxdparam_variant (optional): Variantid of the variant added to the cart as defined in the feed schema. This parameter is optional and needed only if the catalog has variants.
  • unbxdparam_qty (optional): The number of variants that are added to the cart. If not present, the default value assumed is 1.
  • unbxdparam_requestId: The unbxd request id, if available. When the add to cart option is available for the product at the product listing page/recommendation widget, the request id is available. It should be passed with the cart event.
Orders

The below tag needs to be inserted on the order confirmation page.

<li unbxdattr="order" unbxdparam_sku="SKUid" unbxdparam_price="500" unbxdparam_qty="2"></li>  
  • unbxdparam_sku: uniqueId of the product

  • unbxdparam_price: price of the product

  • unbxdparam_qty: quantity of the product bought

Note:

Here, the values of the parameter qty and price can either be within double quotes or without it. However, it is strongly recommended that the price value is kept within double quotes to avoid any value round offs.

2.1.b Tracking on Recommendation Widgets

The below tag needs to be inserted on every product in every recommendation widget:

<li unbxdattr="product" unbxdparam_sku="SKUid" unbxdparam_boxtype="MORE_LIKE_THESE"></li>  
  • unbxdparam_sku: uniqueId of the product.

  • unbxdparam_boxtype: The recommendation Box Type in which the product is displayed. The different types of boxtypes are explained in the table below:

Box Types

The boxtype parameter helps us identify the recommendation widget type. The boxtype values for different widgets are given below:

Widget TypeBox Type
Recommended For You RECOMMENDED_FOR_YOU
Recently Viewed RECENTLY__VIEWED
More Like These MORE_LIKE__THESE
Viewed also Viewed ALSO__VIEWED
Bought also Bought ALSO__BOUGHT
Cart Recommendations CART__RECOMMEND
HomePage Top Sellers TOP__SELLERS
Category Top Sellers CATEGORY__TOP__SELLERS
PDP Top Sellers PDP__TOP__SELLERS
Brand Top Sellers BRAND__TOP__SELLERS
2.1.c Tracking Widget Impressions

Widget Impressions is refers to the rendering of a particular recommendation widget on a page.

Tracking widget impression is important for Unbxd to identify the widgets rendered on a page. The pages where the recommendations are typically shown are:

  • Home Page (HP)
  • Category Listing Page (CLP)
  • Product Detail Page (PDP)
  • Cart Page (CP)
  • Brand Listing Page (BLP)
Home Page (HP)

The impression events in a Home Page for a particular box type can be tracked by inserting the below tag:

<div unbxdAttr="product" unbxdparam_boxtype="BoxType"/>  

For example, to track the impression event of the Recommended For You widget the below tag should be inserted:

<div unbxdAttr="product" unbxdparam_boxtype=" RECOMMENDED_FOR_YOU"/>  
Category Listing Page (CLP)

The impression event in a Category Listing Page for a particular box type can be tracked by inserting the below tag:

<div unbxdAttr="product" unbxdparam_boxtype="BoxType" unbxdparam_category="categoryname"/>  
  • categoryname: name of the category

For example, to track the impression event of the Category Top Sellers widget on Women’s Apparel category, the below tag should be inserted:

<div unbxdAttr="product" unbxdparam_boxtype="CATEGORY_TOP_SELLERS" unbxdparam_category="Women’s Apparel"/>  
Product Display Page (PDP)

The impression event on a Product Detail Page for a particular recommendation widget type can be tracked by inserting the below tag:

<div unbxdAttr="product" unbxdparam_boxtype="BoxType" unbxdparam_source_pid="SKUid"/>  
  • unbxdparamsource _pid: the pid information of the product on which the recommendation widget is displayed.

Note:

Sending the unbxdparam_source_pid information is not mandatory.

For example, to track the impression event of the More Like These widget on the Reebok Men’s Z-PUMP Running Shoes, the below tag should be inserted:

<div unbxdAttr="product" unbxdparam_boxtype="MORE_LIKE_THESE" unbxdparam_source_pid="REEBOKMZPUMPRSHO012"/>  
Cart Page (CP)

The impression event on a Cart Page for a particular recommendation widget type can be tracked by inserting the below tag:

<div unbxdAttr="product" unbxdparam_boxtype="BoxType"/>  

For example, to track the impression event of the Recommended For You widget the below tag should be inserted:

<div unbxdAttr="product" unbxdparam_boxtype=" RECOMMENDED_FOR_YOU"/>  
Brand Listing Page (BLP)

The impression event in a Brand Listing Page for a particular box type can be tracked by inserting the below tag:

<div unbxdAttr="product" unbxdparam_boxtype="BoxType" unbxdparam_brand="brandname"/>  
  • brandname: name of the brand through which the widget impression was loaded.

For example, to track the impression event of the Brand Top Sellers widget on the brand Reebok, the below tag should be inserted:

<div unbxdAttr="product" unbxdparam_boxtype=" BRAND_TOP_SELLERS " unbxdparam_brand="Reebok"/>  

2.2 Using API Calls

You can also track events by configuring API calls on the different website elements. These event-based API calls will track each visitor event and store it in the Unbxd cloud server until the visitor clears the browser cookies. Unbxd has dedicated APIs for tracking the different visitor events.

General Syntax:
Unbxd.track(type,params)  
  • type: is a string which can take these values: "widgetImpression","click","addToCart","order".

  • params: These are parameters that supports the event type that specify the tracking attributes of an event.

2.2.a Tracking across the site

The following tags must be inserted across your site:

Product Clicks:

The API below along with its corresponding event parameter values, needs to be called from your JavaScript on the cart add event.

Every time a visitor clicks on a product in a search results page, category page, or an Unbxd recommendation widget, the following API needs to be called:

API Syntax:

Unbxd.track ( "click" ,{ "pid" : <PID> , "prank" : <PRANK> , "requestId" : <REQUESTID>})  
  • <PID>: uniqueID of the product as passed in the feed.

    Note: Even if your products have variants, please do not pass variant id here. We capture the click on the rolled-up entity and not on the individual variant on the search results page.

  • <PRANK> : rank at which the SKU appears among the search results for a query in the grid/list. The first product will have Rank 1 and so on.
  • <REQUESTID> : The unbxd request id returned in the search/category page/recommendations api call response.

Example:

Unbxd.track( "click" ,{ "pid" : "123" , "prank" : "3" , "requestId" : "607a0bbf-179a-44af-8bdd-e58fef7fc5f3"});  

If you are tracking products clicks on a recommendation widget, you need to call the following API from your Javascript file (in case customer is using Unbxd Recommendations):

API Syntax:

Unbxd.track( "click" ,{ "pid" : <PID> , "prank" : <PRANK> , "boxType" : <BoxType>  
 , "requestId" : <REQUESTID>})  

BoxType (optional): Type of the Unbxd recommendation widget if its one. Please refer ‘Table i’ above for the value of this parameter.

For example:

Unbxd.track ( "click" ,{ "pid" : "123" , "prank" : "3" , "boxType" : "RECOMMENDED_FOR_YOU" , "requestId" : "607a0bbf-179a-44af-8bdd-e58fef7fc5f3"})  

Note: Customer doesn’t have to include this parameter if the recommendation is not powered by Unbxd.

For both HTML attributes and API based, it is recommended to set the information below for better tracking.

For Search result page, you can set the query information (below format) before loading Unbxd analytics tracking plugin:

<script type = "text/javascript">  
      UnbxdAnalyticsConf = window . UnbxdAnalyticsConf || {}; 
      UnbxdAnalyticsConf ["query"] = " nike";
</script>  

For Category result page, you can set the page information (below format) before loading Unbxd analytics tracking plugin:

<script type = "text/javascript">  
     UnbxdAnalyticsConf = window . UnbxdAnalyticsConf || {}; 
     UnbxdAnalyticsConf ["page"] = " nike";
     UnbxdAnalyticsConf [" page_type "] = " CATEGORY_PATH";
</script>  
Add to Cart:

The API below along with its corresponding event parameter values, needs to be called from your JavaScript on the cart add event.

API Syntax:

For products without variants:

Unbxd.track( "addToCart" , { "pid" : <PID> , "qty" : <QTY> , "requestId" : <REQUESTID> })  

For products with variants:

Unbxd.track( "addToCart" , { "pid" : <PID> , "variantId" : <VID> , "qty" : <QTY>  , "requestId" : <REQUESTID> })  
  • <PID>: UniqueId of the product as defined in the feed schema.
  • <VID>: (optional) : Variantid of the variant added to the cart as defined in the feed schema. If not present, Unbxd won’t be able to track variants.
  • <QTY> (optional): The number of variants that are added to the cart. If not present, the default value assumed is 1.
  • <REQUESTID>: The unbxd request id, if available. When the add to cart shortcut is available for the product at the product listing page/recommendation widget, the request id is available. It should be passed with the cart event.

Example:

For products without variants, you can use:

Unbxd.track( "addToCart" , { "pid" : "123" , "qty" : 2 , "requestId" : "607a0bbf-179a-44af-8bdd-e58fef7fc5f3" });  

For products with variants, you can use:

Unbxd . track ( "addToCart" , { "pid" : "123" , "variantId" : "456" ,"qty" : 2 , "requestId" : "607a0bbf-179a-44af-8bdd-e58fef7fc5f3"});  

Note: For both HTML attributes and API based, it is recommended to set the information below for better tracking.

For Search result page, you can set the query information (below format) before loading Unbxd analytics tracking plugin:

<script type = "text/javascript">  
  UnbxdAnalyticsConf = window . UnbxdAnalyticsConf || {}; 
  UnbxdAnalyticsConf ["query"] = " nike";  
</script>  

For Category result page, you can set the page information (below format) before loading Unbxd analytics tracking plugin:

<script type = "text/javascript">  
  UnbxdAnalyticsConf = window . UnbxdAnalyticsConf || {}; 
  UnbxdAnalyticsConf ["page"] = " nike";
  UnbxdAnalyticsConf [" page_type "] = " CATEGORY_PATH";
</script>  
Orders

The below API along with its parameter values needs to be called for every order.

API Syntax:

Unbxd.track("order",{"pid": "PRODUCT-ID","qty": "NO OF PRODUCTS ORDERED","price": "PRICE OF THE PRODUCT"})  

For example:

Unbxd.track("order",{"pid":"123","qty":"2","price":"450"});  

Note:

Here, the values of the parameter qty and price can be either contained within double quotes or without it. However, it is strongly recommended that the price value is within double quotes to avoid any value round offs.

2.2.b Tracking on Recommendation Widgets

The below API along with its parameter values needs to be called for product clicks on a recommendation widget:

Unbxd.track(“click”,{"pid":"PRODUCT-ID", “prank”:"PRODUCT-RANK" “boxType”:"BoxType"})  

2.2.c Tracking Widget Impressions

Widget Impressions tracking is required for Unbxd to understand that a particular widget was rendered on a page in your site. The pages where the recommendations are typically shown are:

  • Home Page (HP)
  • Category Listing Page (CLP)
  • Product Detail Page (PDP)
  • Cart Page (CP)
  • Brand Listing Page (BLP)
Home Page (HP)

The impression event in a Home Page for a particular box type can be tracked by making the below API call:

API syntax:

Unbxd.track("widgetImpression",{"boxType": "BoxType"})  

For example, to track the impression event of the HomePage Top Sellers widget, the below API is called:

Unbxd.track("widgetImpression",{"boxType": "TOP_SELLERS"})  
Category Listing Page (CLP)

The impression event in a Category Listing Page for a particular box type can be tracked by making the below API call:

API syntax:

Unbxd.track("widgetImpression",{"boxType": "BoxType", "identifier":"Category" "pids_list" :  "S0012,S0013,S4530"})  
  • identifier: the clicked category which resulted in a widget impression.

For example, to track the impression event of the Category Top Sellers widget on the Women’s Apparel category, the below API is called:

Unbxd.track("widgetImpression",{"boxType": "CATEGORY_TOP_SELLERS", "identifier":"Women’s Apparel", "pids_list" : "S0012,S0013,S4530"})  
Product Detail Page (PDP)

The impression event on a Product Detail Page for a particular recommendation widget type can be tracked by making the below API call:

API syntax:

Unbxd.track("widgetImpression",{"boxType": "BoxType", "identifier":"pid", "pids_list" : "pid1,pid2,pid3,..."})  
  • identifier: pid on which visitor had clicked which resulted in a widget impression.

For example, to track the impression event of the More Like These widget on the Reebok Men’s Z-PUMP Running Shoes, the below API is called:

Unbxd.track("widgetImpression",{"boxType": "MORE_LIKE_THESE", "identifier":"REEBOKMZPUMPRSHO012", "pids_list' : "S0012,S0013,S4530"})  
Cart Page (CP)

The impression event in a Cart Page for a particular box type can be tracked by making the below API call:

API syntax:

Unbxd.track("widgetImpression",{"boxType": "BoxType", "pids_list" :"pid1,pid2,pid3,..."})  

For example, to track the impression event of the Cart Recommendationswidget the below API is called:

Unbxd.track("widgetImpression",{"boxType": "CART__RECOMMEND", "pids_list" : "S0012, S0013, S4530"})  
Brand Listing Page (BLP)

The impression event in a Brand Listing Page for a particular box type can be tracked by making the below API call:

API syntax:

Unbxd.track("widgetImpression",{"boxType": "BoxType", "identifier":"Brand", "pids_list" : "pid1,pid2,pid3,..."})  
  • identifier: brand on which visitor had clicked which resulted in a widget impression.

For example, to track the impression event of the Brand Top Sellers widget on the brand Reebok, the below API is called:

Unbxd.track("widgetImpression",{"boxType": "BRAND_TOP_SELLERS", "identifier":"Reebok"})  

Once you have correctly placed or configured tags your next step is to integrate the recommendation widgets.