1 Overview
- 1.1 Simple integration
- 1.2 Strict integration
2 Sub-domain Tracking
3 Public API Reference
4 Narrative HTML markup requirements
- - 4.1.1 Container element
  - 4.1.2 Item element
  - 4.1.3 Properties element (optional)
  - 4.1.4 addToBasket element
  - 4.1.5 Basket “quantity” element
  - 4.1.6 Basket “price” element
  - 4.1.7 Basket “currency” element
  - 4.1.8 Detached item element
  - 4.1.9 Sample markup - narrative response element
- 4.2 Overriding standard selectors
- 4.3 Debugging the tracker
5 GTM Integration sample
6 Tracking - URL - Requests
- 6.1 Sample on pageView
- 6.2 Sample on categoryView
- 6.3 Sample on productView
- 6.4 Sample on search
- 6.5 Sample on addToBasket
- 6.6 Sample on purchase
- 6.7 Sample on login

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:

page view event
category view event
search event
product view event
add to basket event
order event
user engagement events (login, clicks, impressions)
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: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/848887816

<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: