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 data-track@blablacar.com 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 data-track@blablacar.com 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
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