Trust Signals: Browser Sensor SDK

This page shows you how to install and use the Trust Signals Browser Sensor SDK, a JavaScript package that collects fingerprint and behavioral observations from the user’s browser. The SDK sends them, through your collection proxy, to the Futurae Collection API.

Package: @futurae-public-js/browser-sensor-js

Prerequisites

• A collection proxy on your backend. The SDK sends observations to it, never directly to Futurae. See Collection proxy.

Before you integrate, read Core Concepts, which explains the identifiers you pass to the SDK.

How the SDK works

1. Your page calls TrustSignalsSDK.initialize() once the user’s identity is known.
2. The SDK records browser events and, every second by default, sends what it has buffered to your proxy with POST.
3. Your proxy sets the collection token and the identity fields, and forwards the request to the Collection API, which replies 202 Accepted.
4. Collection stops when the page navigates away, or when you call TrustSignalsSDK.stopAll().

Collection is scoped to one page load: the upload interval does not survive a navigation. Call initialize() again on every page where you want observations.

Installation

npm, recommended for projects with a build step:

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

UMD bundle, self-hosted, for projects without a build step:

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

Initialization

Call initialize() once on each page, when the current user’s identity is known: for example after the username field is filled, or once the session is established. collectionUrl, serviceId, unitId, accountId, accessToken, interactionId and verificationStatus are all required.

Page JavaScript is directly inspectable by the end user, so anything you pass to the SDK is visible to them. Pass placeholders for accessToken, accountId, interactionId and verificationStatus: your proxy sets the real values.

ES module:

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

TrustSignalsSDK.initialize({
  collectionUrl:      'https://your-backend.example.com/trust-signals/collections',
  serviceId:          'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  unitId:             'mybank-web',
  accountId:          'placeholder',   // your proxy sets the real value
  accessToken:        'placeholder',   // your proxy sets the real collection token
  interactionId:      'placeholder',   // your proxy sets the real value
  verificationStatus: 'unverified',    // your proxy sets the real value
});

UMD bundle:

window.TrustSignalsSDK.default.initialize({
  collectionUrl:      'https://your-backend.example.com/trust-signals/collections',
  serviceId:          'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  unitId:             'mybank-web',
  accountId:          'placeholder',
  accessToken:        'placeholder',
  interactionId:      'placeholder',
  verificationStatus: 'unverified',
});

After initialize(), the SDK sends observations every processIntervalMs, by default every second, until it is stopped.

Configuration options

What each identifier means, and its format rules, are in Identifiers. The recommended values are in Identifier Strategy.

Collected features

The SDK collects all features by default. To restrict collection, pass a features array:

TrustSignalsSDK.initialize({
  // ...
  features: ['mouse_move', 'key_press', 'fingerprint'],
});

Remote Access Tool needs mouse_move, key_press and fingerprint. If you restrict features, keep those three, or that signal cannot be computed.

The individual data points behind each feature are listed in Data Collection and Privacy.

Additional methods

These methods complement the core operation and are not required for it:

TrustSignalsSDK.getSourceObservations();  // Returns the raw collected events array
TrustSignalsSDK.getObservation();         // Returns the mapped observation object, ready for upload
TrustSignalsSDK.stopAll();                // Stops collecting and processing
TrustSignalsSDK.version;                  // The SDK version, as a string

Both getters return null if called before initialize().

Sending observations through your proxy

The SDK sends every upload to the collectionUrl you set at initialization, which is your collection proxy. The real collection token and the user’s real identifiers are added there, so the page holds only placeholders.

For every request it receives from a Sensor SDK, your proxy must:

1. Identify the user. Use your own session mechanism to establish which authenticated user and session the request belongs to. Reject the request if it cannot.
2. Set the identity fields. Overwrite accountId, interactionId and verificationStatus in the request body with the values your backend holds for that user and session, whatever the SDK sent.
3. Set the collection token. Replace the Authorization header with Bearer <collection_token>, using the token your backend holds.
4. Add the client IP address. Set the X-Forwarded-For header to the IP address of the device or browser that sent the request.
5. Forward the request to the Collection API at https://ts-collection-public.futurae.com/api/v1/collections.

The forwarded request, and the status codes to return to the SDK, are in Collection proxy. The Browser SDK has no error callback, so monitor rejected uploads on your proxy.