Trust Signals: Best Practices

This page gives Futurae’s recommendations for where to integrate the Trust Signals components, when to collect, and how to name your identifiers. It ends with a checklist for going to production.

Where to integrate

Mobile apps

Integrate the Mobile Sensor SDK in your authenticator app. Futurae also recommends integrating it in any other app of yours where user activity is meaningful, such as a companion banking app. Give each app its own unitId.

To maximize signal coverage, request the permissions listed in Permissions.

Web pages

Integrate the Browser Sensor SDK in the pages of your web application where you take risk decisions. Which pages are relevant depends on the signals you use:

Signals API

Query the Signals API from the backend component that best suits your use case. Common choices are:

• A fraud detection engine
• An IAM system or identity provider
• A core banking system
• The application backend

The querying component needs the accountId of the authenticating user. To narrow a query to one application, interaction or authentication state, it also needs the values that user’s observations were stored under: the unitId of each SDK instance, and the interactionId and verificationStatus your collection proxy set. It must be able to evaluate the signals it receives, or forward them to a component that can.

When to collect

Signals are computed from stored observations, so a signal is only as fresh as the last upload.

Mobile. Trigger collectAndUpload() on meaningful interactions: app launch, navigation to sensitive screens, and any step involving a transaction or an authentication decision. In addition, schedule background collections every 3 hours to maintain a continuous observation baseline. Immediately before each authentication attempt, trigger one more collectAndUpload(), so that the most recent observations are available when your backend queries.

The operating system runs scheduled collections on a best-effort basis. With a 3-hour interval, expect fewer than the theoretical 8 scheduled observations per day, which is why the on-demand collection before authentication matters.

Browser. The SDK uploads every second while the page is open, so there is nothing to schedule. Initialize it on every relevant page, as early as the user’s identity is known.

Identifier Strategy

Observations are stored under the identifiers you supply and cannot be rekeyed. Define a naming convention before you go to production, and do not change it once observations are being collected.

Futurae recommends a single fixed convention for each identifier, supplied in full on every upload, whatever the use case or page sensitivity. Queries can then supply fewer identifiers, or a shorter interactionId, to cover a wider group, as explained in How a query is scoped:

In the browser, always include the session and page parts of interactionId before the visit identifier. A visit identifier on its own provides no per-session grouping, so queries could only ever address a single page visit. In the order shown, and together with the unitId and verificationStatus that a query with interactionId requires, a query with <sessionID> covers the whole session, one with <sessionID>-<pageID> covers every visit to that page during the session, and the full value covers one visit.

Separate the segments of every identifier with hyphens. Identifiers accept letters, digits and hyphens only, and a value that breaks the format rules is rejected with 400.

Go-live checklist

Before you go to production, confirm that:

1. Identifiers. Your naming convention is settled and documented, and every app and web application has its own unitId.
2. Collection proxy. Your proxy identifies the user from your own session, overwrites accountId, interactionId and verificationStatus, sets X-Forwarded-For, and returns the Collection API’s status code to the SDK. See Collection proxy.
3. Tokens. Both tokens are cached and refreshed on your backend, and neither is passed to an app or a page.
4. Mobile apps. The SDK is initialized at every entry point, your permission requests are designed into the app’s flow, an error handler is registered, and collections run on schedule and before each authentication.
5. Web pages. The SDK runs on every relevant page. If you use Remote Access Tool and restrict features, mouse_move, key_press and fingerprint are still collected.
6. Signals. Your integration branches on success, not on the HTTP status, and checks how old observationTime is before trusting a result.
7. Monitoring. You alert on the ratio of success: false responses against its own baseline. See Troubleshooting.
8. Privacy. Your end users are informed about the data the SDKs collect. See Data Collection and Privacy.