Docs

Unbxd Analytics Integration - REST API

Introduction

We do recommend that the customer follow Browser-based Analytics Integration, where in customer does the integration by including Unbxd javascript library. Unbxd javascript library performs all the operations without the customer investing integration effort. But in case of mobile SDK, alexa or any kind of non-browser based Unbxd integration, customers have to use RESTful API-based analytics integration.

Events

The actions a visitor takes on your ecommerce store are known as Events . The following events can be tracked on your online store:

  • Visitor
  • Search Hit
  • Category Page Hit
  • Product Click
  • Add to Cart
  • Order
  • Product Page View
  • Cart Removal
  • AutoSuggest
  • Recommendation Widget Impression
  • Search Impression
  • Category Page Impression
  • Dwelltime (time spent on a product page)
  • Facets (filters applied for search or browse event)

The calls have to be in the form of an http GET request to the url:

tracker.unbxdapi.com/v2/1p.jpg  

Every request needs to be passed with the following HTTP headers:

  • X-Forwarded-For
  • user-agent

Explanation of the attributes:

1. 'data' :

  • query : The search query entered in the search box.
  • url : The url of the page on which the search query was fired.
  • referrer : The url of the previous page, will be empty if the user opened that particular url directly.
  • visit_type : Can be either "first_time" or "repeat".

2. 'Uid': Unique identifier for the user. Usually we set the "uid" for a particular user in a particular browser. The "uid" is stored in the "uid" cookie and is fetched from it each time. We use the following javascript code to populate this:

var uid = 'uid-' + date . getTime () + "-" + Math . floor ( Math . random () * 100000 );  

3. UnbxdKey: Unique 'isitename' generated for you on the Unbxd platform.

4.'Action' : Determines the type of event that was fired. Its value differs as per the event.

5. 't' (time) : We use the following javascript code to populate this:

t =( new Date (). getTime ()) + "|" + Math . random ();  

It must be unique to avoid caching by the browser, that's why we add a random number after the timestamp.

The different events and the calls to be made in each case are described below:

Visitor

A visitor event is fired to keep track of whether the user is a 'first-time' or a 'repeat' user. Whenever a new user visits the site, a visitor event is fired, that contains information about whether the user is 'first-time' or 'repeat'.

This information is extracted from a 'visitor' cookie which is set every time the visitor event is fired. The cookie maintains the information about "visitType" parameter (also used by other events). Its value can be either 'first-time' or 'repeat'.

This cookie has an expiry time of 30 minutes and after it expires, the visitor event is fired again on a page visit and the same cookie is reset with the new value for 'visitType'. This means, that if the same user is logged on to the same site for more than 30 minutes, his/her visitType will be changed from 'first-time' to 'repeat'.

Implementation:

When a new user visits the page, set a cookie named "unbxd.userid" and set its value in the format below

Format for 'uid' / unbxd.userid (cookie):

It should be a unique identifier for the user. Usually we set the "uid" for a particular user in a particular browser. The "uid" is stored in the "uid" cookie and is fetched from it each time.

We use the following javascript code to populate this:

var uid = 'uid-' + date . getTime () + "-" + Math . floor ( Math . random () * 100000 );  

During this time, also set the value for the cookie "unbxd.visit" to "first_time".

The expiration of cookie "unbxd.visit" should be 30 minutes, so that cookie gets expired every 30 minutes.

Every time the user initiates an event (say, search), check if the value for the cookie "unbxd.visit" is set.
If it is not set and if the "unbxd.userid" is set, set the value for "unbxd.visit" as "repeat" and fire the "visitor" event.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"url": "http://www.example.com/","referrer": "", "visit_type": "repeat", "ver": "2.8.22.1"}&UnbxdKey=demo-unbxd700181503576558&action=visitor&uid=uid-1409753998404-3525 3&t=1429860079584| 0.48704936588183045  

In this case, value of "action" parameter would be “visitor”, other attributes as explained in the beginning.

A search event is fired when a user types something in the search box and presses enter or clicks on the search button. This will take the user to the search listing page.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"query":"meat","url":"http:// www.example.com/","referrer":"","visit_type":"first_time","ver":"2.8.22.1"} &UnbxdKey=demo-unbxd700181503576558&action=search&uid=uid-1427258791138-3017&t=142725911 7476| 0.5922512758988887  

In this case, value of "action" parameter would be “search”, other attributes as explained in the beginning.

Category Page

Category Page event is fired when a user shops by department and visits a category page on the site.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"home/furniture/entrywayfurniture","page_type":"CATEGORY_PATH","url":"https://www.example.com/shop/entrywa  y-furniture/ho0161","referrer":"https://www.example.com/shop/furniture/ho0115","visit_type":"first_time","ver":"2.8.22"}&UnbxdKey=<isitename>&action=categoryPage&uid=uid-1427258791138-3017&t=1427259117476| 0.5922512758988887  

Explanation of the attributes:

  • page: category page visited by the user.
  • page_type: classification of the information passed in the "page" key. Please refer the table below for the corresponding page_type that needs to be passed with respect to the value in page.
pagepage_typeremarks
ho0161TAXONOMY_NODETaxonomy information is available with Unbxd. Send the taxonomy id in page and "TAXONOMY_NODE" in the page_type
home>furnitureCATEGORY_PATHIf the ‘page’ value is simply the ID or name of the associated category, then page_type is "CATEGORY_PATH"
categoryPathId: Parent>ChildBOOLEANIf the ‘page’ value is based on a conditional filter on a certain attribute (categoryPathId is the attribute in this case), then page_type is "BOOLEAN"
https://www.example.com/shop/URLSet page_type to "URL" when tracking hits for a landing page.

Note: Use one of the aforementioned three ways to integrate analytics for tracking department's page hits and the information passed in the page should be consistent with the information present in the catalogue shared with Unbxd.

Search & Category Page Response

For every search, category path and recommendation request that is received at the Unbxd search platform servers a requestId is generated and associated with the request. This id is also sent back to the client by setting it in the response headers.

Sample Request:

$ curl -i  'https://search.unbxd.io/<api_key>/<isitename>/search?q=shirt&fl=product_name'

Sample Response:

HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
Date: Thu, 01 Mar 2018 09:32:34 GMT  
Server: Wingman v0.1.4  
Unbxd-Request-Id: 607a0bbf-179a-44af-8bdd-e58fef7fc5f3  
X-Request-Id: 607a0bbf-179a-44af-8bdd-e58fef7fc5f3  
Content-Length: 2420  
Connection: keep-alive  
{"response":{"numberOfProducts":1418,"start":0,"products":[{"product_name":"Lancôme Juicy Shaker","uniqueId":"10071423"..}

Any subsequent analytics events (preferably clicks and carts on the search and category listing page) fired when the user interacts with the results must provide the requestId of the response responsible for populating the listing page. The details of the analytics integration required so that this information flows to analytics servers has been captured below.

Product Click

Whenever a user clicks on a particular product in the search or category page results, a 'click' action is generated and the following end point has to be hit along with the appended data as described below:

Data required for action: click

API:

https://tracker.unbxdapi.com/v2/1p.jpg? data={"pid":"2301609","url":"https://www.example.com/pdp.jsp?productId=veg_pid_2301609&ca tId=veg_local_csa","referrer":"","visit_type":"repeat", "query": <query>, "page": <page>, "requestId": <requestid>}&UnbxdKey=demo-unbxd700181503576558&action=click&uid=uid-1413889950106-65335&t=1427205349765|0.24967858241871  

Other attributes are same as in "search" event, the only difference being "action" parameter, whose value would be "click" in case of a product click.

Note: If someone lands directly on a product page from other sources (other website or search engine), a 'click' action in that case must also be recorded, and the same end-point must be hit to record the product click.

  • <query>: Sends search query in case of search in the products listing page
  • <page>: Sends the unique identifier for the page passed in the category page API as parameter ‘p’ in case of Category Page.
  • <requestid>: The unbxd request id returned in the search/category page/recommendations api call response.

Product Add to Cart

Whenever a user adds a product to his cart, a 'cart' action is generated and the following end point has to be hit.

https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid":"2301609","qty":2, "url":" https://www.example.com/pdp.jsp?productId=veg_pid_2301609&catId=veg_local_csa","re ferrer":"https://www.example.com/","visit_type":"repeat", "query": <query>, "page": <page> , "requestId": <requestid>}&UnbxdKey=demo-unbxd700181503576558 &action=cart&uid=uid-1413889950106-65335&t=1427205349765|0.24967858241871  
https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid":"<product-id>","variantId ":" < variant - id > " ,"qty ":2, "url ":" https://somesitename.com/collections/new-arrivals/products/randys-i-wish-i-were-hiking-bracelet","referrer":"http://somesitename.com/collections/new-arrivals","visit_type":"repeat","ver":"2.11.5"}&UnbxdKey=somesitename_com-u1405972064004&action=cart&uid=uid-1413889950106-65335&t=1417081469168|0.43562852777540684  
  • <query>: Sends search query in case of cart in the products listing page
  • <page>: Sends the unique identifier for the page passed in the category page API as parameter ‘p’ in case of Category Page.
  • <requestid>(optional): The unbxd request id returned in the search/category page/recommendations api call response, if available. The request id will be available if add to cart option is available for the product at the product listing page/recommendation widget,

Explanation of the attributes:

All attributes are same as that of 'click' event, with the only difference being "action":"cart".

Product Order

An 'order' event will be fired after an order completion, when the user comes back to the site from the payment gateway. If a user buys multiple products in a single order, then multiple order events should be fired.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid": "2301609", "price": 100,"qty" : 1, "url":"https://www.example.com/pdp.jsp?productId=veg_pid_2301609&catId=veg_local_csa","referrer":"https://www.example.com/","visit_type":"repeat"}&UnbxdKey=demo-unbxd700181503576558&action=order&uid=uid-1413889950106-65335 &t=1417081469168|0.43562852777540684  

Explanation of attributes:

  • pid, UnbxdKey, uid, visit_type action, and t are same as click event's.
  • action : Order.
  • price : Price of the product paid by the customer.
  • qty : Quantity of the product bought.

Note : pid should be passed as a string(enclosed in double quotes).

Product Display Page View

Product Display Page View is fired when a user visits a Product Display Page.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid":"6669662","referrer":"https://www.example.com/shop/entryway-furniture/ho0161","url":"https://www.example.com/products/safavieh-hampton-pillowtop-bench-in-blue/6669662":"first_time","ver":"2.8.22"}&UnbxdKey=<isitename>&action=product_view&uid=uid-1427258791138-3017&t=1427259117476| 0.5922512758988887  

Explanation of the attributes:

  • pid: SKU id of the product display page.

Cart Removal

Cart Removal event is fired when a product in cart is removed.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid":"6669662","variantId":"abcdefg","qty":2,"referrer":"https://www.example.com/shop/entryway-furniture/ho0161","url":"https://www.example.com/checkout/bag":"first_time","ver":"2.8.22"}&UnbxdKey=<isitename>&action=cartRemoval&uid=uid-1427258791138-3017&t=1427259117476|0.5922512758988887  

Explanation of the attributes:

  • pid: SKU id of the product.
  • variantId: Id of the variant being removed.
  • qty: Quantity of the product removed from the checkout bag.

AutoSuggest

An autosuggest event is fired when a user types something, then clicks on any of autosuggest results shown.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"query":"Red Socks","autosuggest_data":{"autosuggest_type":"IN_FIELD","autosuggest_suggesti on":"Red Socks","field_value":"Dress Sock","field_name":"infield1","src_field":"color type","pid":null,"unbxdprank":6,"internal_query":"red"},"UnbxdSiteName":"<isit ename>","url":"http://www.example.com/search?q=Pink+Shirt","referrer":"http://www. example.com","visit_type":"repeat","ver":"2.13"}&UnbxdKey=<isitename>&action=searc h&uid=uid-1473341584324-43521&t=1493663167779|0.5231064587647083  

Explanation of the attributes:

  • query: Autosuggest suggestion returned by Unbxd.
  • autosuggest_type: It can be IN_FIELD, POPULAR_PRODUCTS, TOP_SEARCH_QUERIES, KEYWORD_SUGGESTION, PROMOTED_SUGGESTIONS.
  • internal_query: Query for which autosuggest results were generated.
  • field_value: Set when autosuggest_type is IN_FIELD. Set to the value of the "in field" in unbxd response.It is set null otherwise.
  • field_name: Set when autosuggest_type is IN_FIELD. Name of the autosuggest field in the search response.It is set to null otherwise.
  • src_field: Name of the fields present in the catalogue on the combination of which in fields are generated.It is set when autosuggest_type is not null.
  • pid: SKU id of the product.It is set non null when autosuggest_type is POPULAR_PRODUCTS.

Recommendation Widget Impression

If you are subscribed to Unbxd Recommendations, every time the user clicks on any Recommendation widget, the API below needs to be called from your JavaScript file with category name as the parameter.

https://tracker.unbxdapi.com/v2/1p.jpg?data={"box_type":"ALSO_VIEWED","path":"/product","identifier":"1692663-285","pids_list":["1692741-1758","01692015-285","1692908-480","01702359-75","00282168-1758","01792315-1758","1692429-704","01762348-393","01762131-75","01692287-806"],"url":"https://fashion.unbxdapi.com/product?pid=1692663-285","referrer":"https://fashion.unbxdapi.com/","visit_type":"repeat","domain":".unbxdapi.com","_uf":1112242517,"visitId":"visitId-1508916052443-42701"}&UnbxdKey=fashion-unbxdapi-com63470-1490017171&action=impression&uid=uid-1505367433938-23646&t=1508916089173|0.454981110944898  

In this case, the value of "action" parameter would be "impression". "pids_list" would be list of pid's of products visible in window when the event occurs.

Search Impression

A search impression event is fired when a search results page loads for the first time, and whenever results changes on applying pagination, autoscroll, sort, and filters. For each of these action, unique Ids of the products visible on search page should be sent as payload.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"query":"shirt","pids_list":["1692457-319","01692287-806","01692289-75","01692286-75","01692282-172","01702279-75","01702279-393","01702279-1517","01702279-764","9792225-1310","09702112-1455","01702280-998"],"url":"https://fashion.unbxdapi.com/search?q=shirt","referrer":"https://fashion.unbxdapi.com/","visit_type":"repeat","domain":".unbxdapi.com","_uf":1112242517,"visitId":"visitId-1508912632835-36088"}&UnbxdKey=fashion-unbxdapi-com63470-1490017171&action=search_impression&uid=uid-1505367433938-23646&t=1508912975558|0.34440504766324276  

In this case, the value of "action" parameter would be search_impression. pids_list would be list of pid's of products visible in the window when the event occurs.

Category Page Impression

A Category Page Impression event is fired when a category page results loads for first time, and when ever the results changes on applying pagination, autoscroll, sort, and filters. For each of these action, unique Ids of the products visible on search page should be sent as payload.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"/men/shirt", “page_type”: “URL”, "pids_list":["1692457-319","01692287-806","01692289-75","01692286-75","01692282-172","01702279-75","01702279-393","01702279-1517","01702279-764","9792225-1310","09702112-1455","01702280-998"],"url":"https://fashion.unbxdapi.com/men/shirts","referrer":"https://fashion.unbxdapi.com/","visit_type":"repeat","domain":".unbxdapi.com","_uf":1112242517,"visitId":"visitId-1508912632835-36088"}&UnbxdKey=fashion-unbxdapi-com63470-1490017171&action=browse_impression&uid=uid-1505367433938-23646&t=1508912975558|0.34440504766324276  

In this case, the value of "action" parameter would be browse_impression. "pids_list" would be list of pid's of products visible in the window when the event occurs.

Dwelltime (time spent on a product page)

A dwellTime event is used to capture the amount of time spent on product description page.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"pid":"1692663-285","dwellTime":877005,"url":"https://fashion.unbxdapi.com/product?pid=1692663-285","referrer":"https://fashion.unbxdapi.com/","visit_type":"repeat","domain":".unbxdapi.com","_uf":1112242517,"visitId":"visitId-1508916052443-42701"}&UnbxdKey=fashion-unbxdapi-com63470-1490017171&action=dwellTime&uid=uid-1505367433938-23646&t=1508917013109|0.7136163149806576  

In this case, the value of "action" parameter would be "dwellTime". "dwellTime" would have time spent on product description page in milliseconds.

Facets (filters applied for search or Category Page event)

A facet event is fired when a filter is applied on Search or Category pages.

API:

https://tracker.unbxdapi.com/v2/1p.jpg?data={"query":"shirt","facets":{"fit_fq":["Fitted"]},"url":"https://fashion.unbxdapi.com/search?q=shirt","referrer":"https://fashion.unbxdapi.com/","visit_type":"repeat","domain":".unbxdapi.com","_uf":1112242517,"visitId":"visitId-1508916052443-42701"}&UnbxdKey=fashion-unbxdapi-com63470-1490017171&action=facets&uid=uid-1505367433938-23646&t=1508917308101|0.3318202718675367  

In this case, the value of "action" parameter would be "facets". "facets" would have all the selected facets. In case of Category Page, send “page” info instead of “query”.