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 initialize() once when your page loads, passing configuration and credentials as two separate arguments. All TSConfiguration fields except sessionId, features, keyPrefix, and processIntervalMs are required; all TSCredentials fields are required.

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

TrustSignalsSDK.initialize(
  {
    collectionUrl: 'https://your-collection-endpoint/api/v1/collections',
  },
  {
    accountId: 'your-account-id',
    accessToken: 'your-access-token',
    serviceId: 'your-service-id',
    unitId: 'your-unit-id',
    verificationStatus: 'unverified',
    interactionId: 'your-interaction-id',
  }
);

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

window.TrustSignalsSDK.default.initialize({ ... }, { ... });

Config options (TSConfiguration)

| Option | Type | Default | Description | |---|---|---|---| | collectionUrl | string | N/A | Endpoint that receives the collection POSTs | | sessionId | string | auto-generated | Override the session ID (stored in sessionStorage otherwise) | | features | string[] | all features | Subset of features to collect | | keyPrefix | string | __fut_bs_ | Prefix for localStorage keys | | processIntervalMs | number | 1000 | How often (ms) collected data is sent |

Credentials (TSCredentials)

| Option | Type | Description | |---|---|---| | accountId | string | Your account identifier | | accessToken | string | Sent as a Bearer token in the Authorization header | | serviceId | string | Your service identifier | | unitId | string | Your unit identifier | | verificationStatus | string | One of: verified / unverified / fraud | | interactionId | string | A non-static (per-interaction) identifier |

API

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

// Get the raw collected events (array)
TrustSignalsSDK.getSourceObservations();

// Get the transformed observation object ready for a request
TrustSignalsSDK.getObservation();

// Stop collecting and processing, and release background resources
TrustSignalsSDK.stopAll();

// Installed SDK version
TrustSignalsSDK.version;

Collected features

By default the library collects all of the following. The Key column is the feature code passed to features; the Observation field column is the corresponding key in the object returned by getObservation(). Feature codes use the same full names as the observation fields.

| Key | Observation field | Description | |---|---|---| | mouse_move | mouse_move / mouse_move_xy | Mouse move timestamps and coordinates | | mouse_up | mouse_up / mouse_up_xy | Mouse up timestamps and coordinates | | mouse_down | mouse_down / mouse_down_xy | Mouse down timestamps and coordinates | | key_press | key_press | Key press durations (down/up pairs); covers both keydown and keyup. | | fingerprint | deviceInfoSignals (sibling of observation, not inside it) | Browser fingerprint | | form_focus | form_focus | Input/textarea focus events | | form_blur | form_blur | Input/textarea blur events |

To collect only a subset pass a features array using the feature code strings above:

TrustSignalsSDK.initialize(
  {
    collectionUrl: 'https://your-collection-endpoint/api/v1/collections',
    features: ['mouse_move', 'key_press', 'fingerprint'],
  },
  { /* ...TSCredentials */ }
);

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