# 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

```json
{
  "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:

```javascript
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

```javascript
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)_

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

_Cookie (JS)_

```javascript
import Cookies from 'js-cookie'

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

_Local Storage (JS)_

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

### Send an event

```javascript
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

```javascript
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.

```javascript
Tracktor.userConfig
```