browser-sensor-js

JavaScript library used client-side for browser behaviour collection (mouse, keyboard, fingerprint, etc.).

Building browser-sensor.min.js

To build the minified bundle we use webpack. In the root folder you will find:

• package.json, includes all necessary npm scripts and packages
• webpack.config.js, includes all necessary configuration options and plugins

To install all necessary packages run:

yarn

To build for development with watch mode:

yarn build:dev

To build a production bundle:

yarn build

The bundle is placed under dist/browser-sensor.min.js.

Test locally

• Create a bundle with yarn build
• Run a server with npx serve
• Open http://localhost:3000 in the browser
• Interact with the page and check the Network tab to see the outgoing observation payloads

Usage

Install

npm install @futurae-public-js/browser-sensor-js

Or load the UMD bundle directly in HTML:

<script src="node_modules/@futurae-public-js/browser-sensor-js/dist/browser-sensor.min.js"></script>

Init

Call init() once when your page loads. All fields except sessionId, collector, storage, and processor are required.

import browserSensor from '@futurae-public-js/browser-sensor-js';

browserSensor.init({
  baseURL:   'https://your-collection-endpoint/api/v1/observations',
  accountID: 'your-account-id',
  appID:     'your-app-id',
});

When using the UMD bundle the library is exposed as window.browserSensor.default:

window.browserSensor.default.init({ ... });

Config options

| Option | Type | Default | Description | |---|---|---|---| | baseURL | string | — | Endpoint that receives the observation POSTs | | accountID | string | — | Your account identifier | | appID | string | — | Your application identifier | | authToken | string | — | Authorization token sent in the Authorization header | | sessionId | string | auto-generated | Override the session ID (stored in sessionStorage otherwise) | | collector.features | string[] | all features | Subset of features to collect | | storage.keyPrefix | string | __fut_bs_ | Prefix for localStorage keys | | processor.processInterval | number | 1000 | How often (ms) collected data is sent |

API

// Get the current session ID
browserSensor.getSessionId();

// Get the raw collected events (array)
browserSensor.getData();

// Get the transformed/mapped observation object
browserSensor.getTransformedData();

// Stop collecting and processing
browserSensor.stop();

Collected features

By default the library collects all of the following:

| Key | Description | |---|---| | mm | Mouse move timestamps and coordinates | | mu | Mouse up timestamps and coordinates | | md | Mouse down timestamps and coordinates | | kp | Key press durations (down/up pairs) | | fp | Browser fingerprint | | window_init | Window dimensions at initialisation | | window_resize | Window resize events | | input_form_focus | Input/textarea focus events | | input_form_blur | Input/textarea blur events |

To collect only a subset pass a collector.features array using the feature key strings above:

browserSensor.init({
  // ...
  collector: {
    features: ['mm', 'kp', 'fp'],
  },
});

Environments

Environment variables for each build target are stored in .env-cmdrc.json. To add a new environment, add a key there and build with:

yarn env-cmd -e staging webpack