JS Tracker API

Overview 

Boxalino Client Tracking API is a pure javascript library without dependencies to trigger event notifications such as page views or purchases. 

The javascript library associates an unique identifier with each visitor and collects information on the source of the track as well as a few selected demographic data (language, screen size, browser version and similar technical parameters). 

Some of the major tracking events which can be integrated are:

  1. page view event

  2. category view event

  3. search event

  4. product view event

  5. add to basket event

  6. order event

  7. user engagement events (login, clicks, impressions)

  8. custom events (per your setup requirements)

The integration is very similar to the Google Analytics integration on any e-shop.

The basic integration takes only a few minutes.

Simple integration

In order to integrate the library simply add the following html snippet to your page header:

<script type="text/javascript"> var _bxq = _bxq || []; _bxq.push(['setAccount', 'ACCOUNTID']); _bxq.push(['setLanguage', 'LANGUAGE']); _bxq.push(['trackPageView']); // additional event such as 'trackCategoryView' should be inserted here (function(){    var s = document.createElement('script');    s.async = 1;    s.src = '//track.bx-cloud.com/static/bav2.min.js';    document.getElementsByTagName('head')[0].appendChild(s); })(); </script>

This will send a page view event in the account ‘ACCOUNTID. Boxalino will provide your account identifier.

Strict integration

Tracker only reads cookies, mandates manual opt in.
See also: Data Privacy Guidelines for Tracking

<script type="text/javascript"> var _bxq = _bxq || []; _bxq.push(['setOptions', {'requireOptIn': true, 'writeCookies': false, 'profileCookie': 'myProfileCookie', 'sessionCookie': 'mySessionCookie'}]); _bxq.push(['setAccount', 'ACCOUNTID']); _bxq.push(['setLanguage', 'LANGUAGE']); _bxq.push(['trackPageView']); (function () { var s = document.createElement('script'); s.async = 1; s.src = '//track.bx-cloud.com/static/bav2.min.js'; document.getElementsByTagName('head')[0].appendChild(s); })(); // notify the tracker once the user opts in. note that this has to be set every time, the tracker does not remember its opt-in state. // <custom code tracking optIn state> // _bxq.push(['setOptions', {'optIn': true}]); </script>

Sub-domain Tracking

In order to track your visitors properly across several sub-domains (ie. between promo.yoursite.com and www.yoursite.com) the following call must be done before any event tracking: 

<script type="text/javascript"> var _bxq = _bxq || []; _bxq.push(['setAccount', 'ACCOUNTID']); _bxq.push(['setLanguage', 'LANGUAGE']); _bxq.push(['setCookieDomain', 'yoursite.com']); _bxq.push(['trackPageView']); (function(){ var s = document.createElement('script'); s.async = 1; s.src = '//track.bx-cloud.com/static/bav2.min.js'; document.getElementsByTagName('head')[0].appendChild(s); })(); </script>

 The cookie domain is simply the top-level name alone (ie. www.yoursite.com becomes yoursite.com). This code need to be installed on all active sub-domains.

Public API Reference

A detailed description of all accessible functions of the API follow.

Because the API is loaded asynchronously the _bxq object will not be accessible at page load. So the preferred way of calling tracking methods is through the array syntax. 

Example of triggering a page view event asynchronously:

integration by convention

If you’re using narratives and have integrated them properly using bx-attributes, the following events will work automatically for narrative blocks:

  • click

  • impression

  • addToBasket*

* requires additional tagging.

the ‘parameters’ parameter

Many methods support parameters as a way to add additional meta-info to an event. The parameters must always be a javascript object with string keys and string values.

Example:

void setAccount(accountId)

Set current account identifier for the tracking.

The effect is immediate and it returns nothing.

void setLanguage(language)

Set the current language - this should be the language that the user sees the page in and match what is sent via the narrative request (e.g. "de").

The effect is immediate and it returns nothing.

void setCookieDomain(domain, path)

Set domain and path for visitor cookies.

If the domain is unspecified the current domain is taken. Path is optional and defaults to /. 

The effect is immediate and it returns nothing.

void setOptions(kv)

Set custom tracking options.

Option

Default

Description

Option

Default

Description

profileCookie

cemv

changes the name of the profile cookie

sessionCookie

cems

changes the name of the session cookie

writeCookies

true

if false, does not modify cookies at all

optIn

false

if false and requireOptIn is true, pauses sending of events until it is set to true. events are still collected (and lost if optIn is never set to true before the user navigates)

requireOptIn

false

requires optIn to be true to send events to the tracker endpoint

maxage

31536000000

maximum age of the profile cookie in milliseconds

The effect is immediate and it returns nothing.

void setTrackerUrl(url)

Changes the tracker endpoint. 

This is only necessary if you want to proxy the events through your own environment for example.

The effect is immediate and it returns nothing.

string getVisitor()

Get current visitor identifier. It returns the visitor identifier as a string

string getSession()

Get current session identifier. It returns the session identifier as a string.

string getUser()

Get current user identifier.

 It returns the user identifier as a string or "undefined" if no user has been set for that visitor before.

void setUser(userId)

Set current user identifier. 

This should be called after a registered user logs-in. The effect is immediate and it returns nothing.

void trackPageView(uri, parameters)

Send a page view event to the tracker. 

The URI, page, variant and parameters are optional. If the URI is not given - the current browser URI is taken. The key-value parameters can be used to append extra meta-data to the event. 

void trackCategoryView(category, parameters) 

Send a category view/browse event to the tracker. 

The category id is required.

void trackSearch(query, parameters) 

Send a search view/browse event to the tracker. 

The query is required.

void trackProductView(product, parameters)

Send a product view event to the tracker. 

The product id is required.

The PRODUCTID must be the sku.internal_id (id field) and not the products_group.internal_id (products_group_id field). If your Product Page doesn’t select one sku by default, then just provide the first one of your list.

You can send this event again, every time the user changes the selected SKU.

void trackAddToBasket(product, quantity, price, currency, parameters)

Send an add-to-basket event to the tracker. 

The following context is to be defined:

  1. product identifier (mandatory)

  2. quantity (optional): integer to specify how many times the product has been added to the basket (for this event).

  3. price (optional):  product price represented as string

  4. currency (optional):  a string identifier (such as 'CHF')

avoiding duplicate addToBasket events for narrative blocks

Please ensure that addToBasket events that are already covered automatically are not tracked again by your manual integration.

Your manual integration might looks similar to this example using jQuery:

Exclude elements that are already covered automatically as follows:

void trackPurchase(total, currency, products, orderId, parameters)

Send a purchase event to the tracker. 

The following context is to be defined: 

  1. total amount: total price represented as string

  2. currency: a string identifier (such as 'CHF')

  3. products - array of purchased products:

    1. productID field (mandatory)

    2. quantity and price - optional

  4. orderId (optional) - the order connected with the event

void trackLogin(userId, parameters)

Send a login event to the tracker. 

The user id is required.

void trackEvent(name, parameters)

Send a custom event including the parameters required per your own logic.

The 1st parameter must be trackEvent.

The 2nd event is your custom event name and should be representative to the use-case integrated.

The parameters must always be a javascript object with string keys and string values.

Narrative HTML markup requirements

NEW : Now supporting also scrolling and click tracking outside of Boxalino Narrative. Follow our Guide here to learn more about it!

For the narrative tracking (clicks / impressions) to work correctly the HTML has some loose requirements that need to be met.

If you have already integrated bx-attributes properly, except for the addToBasket case, these requriements should already be met.

Container element

The container element may contain nested container elements as well as item elements.

If the container is a slider, the slider's overflow element (overflow-x == hidden) must be the container element itself or a child of the container.

  • must have css-class 'bx-narrative'

  • should have attribute 'data-bx-narrative-name'

Item element

The item element should contain exactly one item (e.g. product).

  • must be a child of the container element

  • must have css-class 'bx-narrative-item'

  • must have attribute 'data-bx-item-id' with the item’s id

Properties element (optional)

The narrative properties element is an optional element that may be provided as parent element of multiple narrative containers. It can be utilized to group common properties.

  • must be the parent of multiple container or detached item elements

  • must have css-class 'bx-narrative-props'

  • must have at least one ‘data-bx-*’ attribute

addToBasket element

This is the button that adds the item to the basket

  • must be a child of the item element

  • must have css-class 'bx-basket-add'

Basket “quantity” element

The quantity element is optional and defaults to 1.

  • must be a child of the item element

  • must have css-class 'bx-basket-quantity'

Basket “price” element

The price element is optional and should contain the price with or without currency of the item.

  • must be a child of the item element

  • must have css-class 'bx-basket-price'

Basket “currency” element

The currency element is optional and only necessary if the currency isn't already contained in the price.

  • must be a child of the item element

  • must have css-class 'bx-basket-currency'

Detached item element

A detached item element is classified as such if it doesn’t have a narrative container.

Sample markup - detached element:

Sample markup - narrative response element

Sample markup showcasing one container with three items. Obviously, the values for the 'data-bx-*' attributes have to be dynamic.

Overriding standard selectors

You can override the selectors and therefore the css-class requirements as stated above. Note that the tracker uses querySelectorAll which behaves differently than JQuery's selectors.

Option

Default

Option

Default

narrative.selector-container

.bx-narrative

narrative.selector-item

.bx-narrative-item

narrative.selector-props

.bx-narrative-props

narrative.selector-link

a, *[href], .bx-narrative-button

basket.selector-add

.bx-basket-add

basket.selector-quantity

.bx-basket-quantity

basket.selector-price

.bx-basket-price

basket.selector-currency

.bx-basket-currency

Options may be set as follows, as part of the tracker integration:

This particular example allows either 'my-container' or 'my-slider' as container class and 'my-item' or 'my-slider-item' as item class. 'my-item' is also preceded by '.my-container ' which means that a matching item must have a parent in the dom with that class.

Debugging the tracker

Once the tracker is presumably set up correctly the testing process can be simplified by entering debug-mode.

Run the following script in your browser's console to enter debug-mode for the duration of the session.

GTM Integration sample

If you want to integrate the boxalino tracking in your Google Tag Manager account, create a new tag and add the following HTML-Code, making sure, that you replace your account and domain names (marked bold in the example below)

 

Tracking - URL - Requests

Besides integrating the JavaScript tracker, the events can be sent to the Boxalino tracking server directly.

Some of the _GET parameters used for the samples are:

  _a - account (provided by Boxalino)

 _t - microtime (milliseconds) since start of UNIX epoch as returned by the javascript engine of browser (not reliable)

  _bxv - the value of the visitor cookie, unique per visitor and device

  _bxs - the value of the session cookie, unique per session, visitor and device

  _ev - the event type, i.e. pageView, search, login, etc.

  _src - if this is a direct (meaning from the JS tracker) request or an organic one

  _scr - information about the visitors screen resolution

 _frm - information about the visitors browser view port size, the part of the screen that is actually displaying the website

  _ln - language in ISO notation

  _tx - session storage, typically "cookie,storage"

   id - value depending on the event type. For the productView its the product ID, the category ID for categoryView, the page URL for a pageView, the search query for a search, etc.

  q - quantity for addToBasket events

   p - price for addToBasket events (optional)

   c - currency code for addToBasket events (optional)



Depending on your configurations (using dev index or production index for the client), the host will differ: 



Sample on pageView

https://track.bx-cloud.com/track?id=%252Fde%252Fcollection%252F0%252Fproduct%252F69352%252Foption%252F200334&_a=<ACCOUNTID>&_t=1428392929768&_bxv=3bc86006.110e7ebe.ce.14c92d9952d&_bxs=3bc86006.53d7a2be.31d.14c92d9952e&_ev=pageView&_rf=<REFERRER-URL>&_src=direct&_scr=1920x1200&_frm=1920x943&_ln=de&_tx=cookie%252Cstorage&&&



Sample on categoryView

https://track.bx-cloud.com/track?id=travel&_a=<ACCOUNTID>&_t=1428394624988&_bxv=64b8b7e6.6725053e.11f.14c89b0b8dc&_bxs=64b8b7e6.7730f03e.265.14c92e5d544&_ev=categoryView&_rf=<REFERRER-URL>&_src=direct&_scr=1280x720&_frm=1132x657&_ln=fr-CH&_tx=cookie%2Cstorage&&&



Sample on productView

https://track.bx-cloud.com/track?id=209671&_a=<ACCOUNTID>&_t=1428394627257&_bxv=f33c325.b1d7242.129.14c4c263169&_bxs=f33c325.169a6dfe.ef.14c92f35987&_ev=productView&_rf=<REFERRER-URL>&_src=direct&_scr=1755x987&_frm=1755x854&&_tx=cookie%2Cstorage&&&



Sample on search

https://track.bx-cloud.com/track?id=weinregal&_a=<ACCOUNTID>&_t=1428394612023&_bxv=3df1eb0.56dc1942.35c.14c92f0bf10&_bxs=3df1eb0.1323b07e.c8.14c92f0bf11&_ev=search&_rf=<REFERRER-URL>&_src=direct&_scr=1920x1080&_frm=1920x934&_ln=de-CH&_tx=cookie%2Cstorage&&&



Sample on addToBasket

https://track.bx-cloud.com/track?id=206613&q=1&p=49.0&c=CHF&_a=<ACCOUNTID>&_t=1428394664134&_bxv=28387b5b.127d307e.289.14c7588c6b3&_bxs=41c8ab0.1019be.135.14c92ef6e1f&_ev=addToBasket&_rf=<REFERRER-URL>&_src=direct&_scr=1920x1080&_frm=1920x958&_ln=de&_tx=cookie%2Cstorage&&&



Sample on purchase

https://track.bx-cloud.com/track?t=739.8&c=CHF&n=3&orderId=45871669&id0=93092&q0=1&p0=649&id1=176400&q1=1&p1=24.9&id2=152451&q2=1&p2=39&_a=<ACCOUNTID>&_t=1427984556211&_bxv=b94ab40.67db60fe.3d9.14c7a724c43&_bxs=b94ab40.6433717e.365.14c7a7f1d39&_ev=purchase&_rf=http%3A%2F%2Fcheckout.lvh.me%3A3000%2Fde%2Fcart%2Ffinalize&_src=direct&_scr=1920x1080&_frm=1052x993&_ln=en-US&_tx=cookie%2Cstorage&&&



Sample on login

https://track.bx-cloud.com/track?id=<USER-ID>&_a=<ACCOUNTID>&_t=1428394663487&_bxv=524f7a67.3bc63e82.91.14c92f4de3b&_bxs=524f7a67.1076d342.1c6.14c92f4de3c&_ev=login&_rf=<REFERRER-URL>&_src=organic&_scr=1280x800&_frm=1159x621&_ln=de-de&_tx=cookie%2Cstorage&&&