Tracktor JS Library

https://www.npmjs.com/package/@blablacar/tracktor

Tracktor is a user behavior tracking solution. Through the usage of events, it is sending the user actions, after which the events are computed and integrated into the BlaBlaCar datawarehouse.

Tracktor JS Library is basically a queue in charge of collecting and periodically pushing standardized events into Tracktor.

Creating an event

Send an email to [email protected] to request the implementation of a new event.

Event composition

| Field | Type | Description | | ------- | :----: | -------------------------------------: | | name | String | Name of the event | | version | Number | Version of the event | | payload | Object | Payload defined in the event whitelist |

Event schema proposal template

{
  "name": { "enum": ["EVENT_NAME"] },
  "version": { "enum": ["EVENT_NUMBER (number)"] },
  "payload": {
    "properties": {
      "FIELD_1": { "type": "string" },
      "FIELD_2": { "type": "number" },
      ...
    },
    "required": ["FIELD_1"]
  }
}

Event Testing

Here are the process to test the validity of your library implementation, and the reception in the expected format of your events:

• [TODO] Use the test event (ongoing)
• [TODO] Use the preprod kibana to track your test event (ongoing)

How to use?

If you are using Tracktor on a new domain, send an email to [email protected] in order to ensure the backend whitelisting. Please, also agree with an app name.

Documentation

Environment

The library is functional both client side and server side, so it works fine with isomorphism apps.

Event Buffer

The library is using an internal event buffer to push the events. You can create several TracktorJS instances, they will all use the same Event Buffer (particularly interesting server side, the event buffer is not request based).

You will need to configure the event buffer, at least to provide the backend URL:

| Field | Type | Description | Default | | ----------------- | :------: | ---------------------------------------------------------------------: | :----------: | | sendUrl | String | Backend url where the events will land | | | appName | String | Name of your application to easily filter the logs | | | emit_frequency | Number | Delay to flush the event queue when there is at least one event pushed | 2000 | | event_max_count | Number | Maximum number of events able to be pushed at once | 20 | | event_max_size | Number | Maximum event size able to be pushed (single event) | 2500 | | request_max_size | Number | Maximum events size able to be pushed (several events) | 10000 | | retries_frequency | Number | Number max of retry when the event buffer flush is failing | 5 | | onSendFailure | Function | Callback on request fail | function(){} |

All of these values can be overriden for every instance created by Tracktor once by doing:

import TracktorJS from '@blablacar/tracktor'

const config = {
  appName: 'app-web',
  sendUrl: 'http://domain.com',
  onSendFailure: error => {
    console.log(error)
  },
}
TracktorJS.initializeEventBuffer(config)

Create an instance

import TracktorJS from '@blablacar/tracktor'
const userConfig = {
  userAgent:
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36',
  hostname: 'www.hostmame.com',
}
const storage = {
  get: getCookie,
  set: setCookie,
}
new TracktorJS(userConfig, storage)

We explained earlier, Tracktor is a user behavior tracking solution, so the constructor includes two required parameters:

UserConfig

| userConfig fields | Type | Required | Generated if not provided | | ----------------- | :----: | :------: | ------------------------: | | userAgent | String | true | false | | hostname | String | true | false | | locale | String | false | false | | userId | String | false | false | | ip | String | false | false | | deviceId | String | false | true | | sessionStamp | Number | false | true | | visitorId | String | false | true | | deviceBrand | String | false | defaults to 'UNKNOWN' | | deviceModal | String | false | defaults to 'UNKNOWN' | | osName | String | false | defaults to 'UNKNOWN' | | osVersion | String | false | defaults to 'UNKNOWN' |

Storage

The storage is essential for Tracktor, for the deviceId, sessionStamp and visitorId. These values need to be persistent, and regarding your app, you might like to store it in a very different way (cookies for node, local storage for browser etc.).

| storage fields | Signature | Required | Description | | -------------- | :---------------------------: | :------: | ----------------------------: | | get | (key) => number | string | true | Retrieve the value from your storage | | set | (key, value, options) => void | true | Set the value in your storage |

Example:

Cookie (Node JS, Express)

const storage = {
  get: name => req.cookies[name],
  set: (...args) => res.cookie(...args),
}

Cookie (JS)

import Cookies from 'js-cookie'

const storage = {
  get: Cookies.get,
  set: Cookies.set,
}

Local Storage (JS)

const storage = {
  get: (...args) => localStorage.getItem(...args),
  set: (...args) => localStorage.setItem(...args),
}

Send an event

const EVENT_NAME = {
  name: 'event_name', // whitelisted event name
  version: 1, // whitelisted version
}
const payload = {
  route: '/', // whitelisted payload
}
Tracktor.push(EVENT_NAME, payload)

Flush the queue

Tracktor.flush()

Retrieve the User config

Since some internal values can be generated, the full userConfig is not always known by the user of the library.

Tracktor.userConfig