SDK

Guide to using the SDK for FHR and XO tracking: install via CDN or npm, track client-side interactions, and customize event handling and data integration.

The SDK is a JavaScript library. It can be used on both the client-side and on the server-side. The SDK supports tracking features for FHR and XO systems, enabling a wide range of use cases.

We recommend SDK to implement detailed, real-time tracking that integrates smoothly with your website's flow and infrastructure, while offering customization for user behavior, event handling, and data integration.

The SDK is especially suited for:

• Client-side tracking

• Tracking specific user interactions with a high level of control and flexibility

Installation

The xo library is used for both FHR and XO.

You can install the tracker using either CDN or npm methods:

• For browser-based implementations, use the client from our CDN.

• For more advanced use cases involving a bundler and server-side tracking, use the npm package.

CDN installation

To make SDK available, inject the following script via your TMS or simply embedd it on your platform:

<script type="text/javascript">
!function(att,raq,t){
    var version = "2";
    var supportOldBrowsers = false;
    att[raq]=att[raq]||[];var n=["init","send","setUser","addUserIdentity","setUserIdentities","addUserSegment","setUserSegments","addUserTrait","setUserTraits","clearUser","getUserClusters"];if(!att.xo){att.xo={activity:{},init:function(e){att[raq].push(["init",e.activity])}};for(var r=0;r<n.length;r++)att.xo.activity[n[r]]=function(e){return function(r,s,a){att[raq].push([n[e],r,s,a])}}(r)}var s=document.createElement("script");s.type="text/javascript",s.async=!0,s.src=t+version+".min.js",(att.document.documentMode||supportOldBrowsers)&&(s.src=t+version+".compat.min.js");var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(s,a);
}(window,"_attraqt","https://cdn.attraqt.io/xo.all-");
</script>

Inject this snippet as early as possible - preferably in the header. We have purposely kept the client lightweight to ensure it does not slow down your page.

To avoid missing any events, start sending events even before the client is fully loaded. This is enabled by the built-in queuing system.

CDN advanced options

The client is designed to work on all recent browsers. If you require support for legacy browsers, set the supportOldBrowsers option to true.

<script type="text/javascript">
!function(att,raq,t){
    var version = "2";
    var supportOldBrowsers = true;
    att[raq]=att[raq]||[];var n=["init","send","setUser","addUserIdentity","setUserIdentities","addUserSegment","setUserSegments","addUserTrait","setUserTraits","clearUser","getUserClusters"];if(!att.xo){att.xo={activity:{},init:function(e){att[raq].push(["init",e.activity])}};for(var r=0;r<n.length;r++)att.xo.activity[n[r]]=function(e){return function(r,s,a){att[raq].push([n[e],r,s,a])}}(r)}var s=document.createElement("script");s.type="text/javascript",s.async=!0,s.src=t+version+".min.js",(att.document.documentMode||supportOldBrowsers)&&(s.src=t+version+".compat.min.js");var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(s,a);
}(window,"_attraqt","https://cdn.attraqt.io/xo.all-");
</script>

This option loads a polyfilled version of our library, which increases its weight.

The version can either be a major version, which will allow you to benefit from all the backward compatible updates automatically, or an exact one (x.x.x). You can find a list of all available version here.

NPM installation

To install the SDK via npm, add the xo-js client to your npm dependencies:

npm install --save @attraqt/xo-js

Our package is written in TypeScript and natively supports it.

Typescript

import * as xo from '@attraqt/xo-js';

Javascript

Initialization

Once the SDK is installed, initialize it to start tracking user activities:

1. Call the init function to set up the tracker with your unique trackerKey.

2. Include other configurations such as region and storage.

To obtain your tracker key(s), reach out to your Customer Support Manager.

The init function must be called before you interact with the SDK to ensure that all necessary configurations are set up, and the SDK is ready to track data. This prevents issues such as missed events, improper data collection, and user identification problems. It is a critical first step in the integration of the SDK, and it should be executed early in your application's lifecycle to ensure accurate and consistent tracking. This can be done in the <head> section of your website or at the start of your JavaScript code, ensuring that the SDK is available for tracking from the very beginning.

The init function is available under the xo , xo.activity and xo.search namespace:

• xo.init({activity: {activityOptions}, search: {searchOptions}})

• xo.activity.init({activityOptions})

• xo.search.init({searchOptions})

xo.init and xo.activity are both for FHR & XO, xo.search is for XO Search customers only

The activityOptions parameters are:

• trackerKey : Your unique trackerKey to enable the tracking functions

• region (optional): The region where the activity pipeline is running; currently only EU is available, and is enabled by default

• storage (optional): Used to define custom storage

The searchOptions parameters are:

• token: your unique Search token, available in your Console at this address. The right token that corresponds to the XO tenant needs to be used.

• region: the region in which your data is stored. Available regions are listed below, and the default is EU.

Supported regions	Code
Europe (default)	EU
United States	US
Australia	AP2

Inline HTML

<script type="text/javascript">
    xo.init({
        activity: {
            trackerKey: 'YOUR TRACKER KEY',
            region: 'YOUR REGION'
        }
    });
</script>

Javascript

To prevent possible loss of data, you should always initialize the client and identify the user before sending activities.

Handling

Once the SDK is initialized, you can interact with it to send and manage tracking events. Below you can find a simple example of how to register a view action for a product with the ID 123.

Execute the following JavaScript snippet using the SDK, or make the following API call:

// First, import the library
const xo = require('@attraqt/xo-js');

// Next, initialize the SDK with your tracker key
xo.init({activity: {trackerKey: '30cbb5fc-375f-4cf2-8efd-ed86d909718e'}});

const myActivity = {
  "action": "view",
  "target": {
    "product": "123"
  },
  "user": {
    "identities": {
      "sessionId": "2ee80450-28ed-11eb-adc1-0242ac120002"
    }
  }
};

// Then, use the send() method of the SDK
xo.activity.send(myActivity);

Activity object

• action field: Represents the action the user performed Example: "view" represents a view on a product

• target object: Covers the details of the target of the action (view) Example: { product: "123" } specifies a product with ID 123

• user object: Contains the identities; Example: { identities: { sessionId: "2ee80450-28ed-11eb-adc1-0242ac120002" } } specifies the session ID

The above example provides only minimal information. Include additional details in the activity object to enhance the quality of analytics.

You can read more on the activity object here.

Identities

In order to be able to perform analytics on the actions of shoppers, you need to be able to distinguish users of all the events you send. This allows you to link different actions a shopper makes, such as clicks, purchases etc., to better understand their behaviour, and improve their shopping experience. This is where identities management comes in.

At least one identity, the session ID, is required to send events to the tracking system. You can find more information on managing identities here.

Response

If your integration is correctly configured, you will receive a successful 201 response. Any issues with the tracker key, SDK, or endpoint trigger an error message. Should you experience any problems, contact Crownpeak Professional Services for further assistance.

Using custom storage

By default, when the SDK library is initialized, it uses default storage mechanisms that depend on the environment in which it is running.

Browser environments

In browser environments, localStorage is used to store tracking data by default. This ensures that data persists across browser sessions for the same user. This way tracking data remains accessible even after a page reload or session restart.

Node.js environments

For server-side implementations using Node.js, a variable is used instead of localStorage. Since Node.js does not have access to localStorage (a browser-specific feature), the SDK uses a variable to temporarily hold the tracking data during the session.

However, you may need to use custom storage if you need to integrate with an external storage system, or require specific data storage behavior.

To use custom storage, initialize the SDK with custom storage. Use the storage option as described below:

HTML

<script type="text/javascript">
    xo.init({
        activity: {
            trackerKey: 'YOUR TRACKER KEY',
            region: 'YOUR REGION',
            storage: myCustomStorage
        }
    });
</script>

NodeJS

The storageparameter takes a custom storage object with the same methods as the localStorage API. See localStorage documentation for the four methods:

Method	description
setItem(key, value)	The value to be stored and its key
getItem(key)	Return the value for given key from storage
removeItem(key)	Remove key and value from storage
clear()	Clear storage

All key and value parameters must be strings.

Once you have succesfully set up the use of custom storage:

• Store data: Any data sent through the SDK will be stored using the setItem() method.

• Retrieve data: When fetching data, the SDK uses the getItem() method to retrieve the data.

• Clear data: You can use clear() to reset all stored data, which might be necessary when a user logs out or a session expires.