Trulioo SDK - Web Guide

Quick Summary

The Trulioo Web SDK initializes a shortcode-backed session and exposes base verification capabilities for browser applications.

Customer applications can expect the SDK to:

• initialize an authorized session from a shortcode
• support configured Device Intelligence capabilities
• return capability results, errors, and diagnostic information
• leave journey decisions and customer policy to the host application

A standard web integration looks like this:

1. install @trulioo/trulioo
2. initialize with a shortcode
3. collect Device Intelligence when required by the journey
4. use the result to continue, retry, or route the journey for review

Installation

npm install @trulioo/trulioo

Example import:

import { Trulioo } from "@trulioo/trulioo";

Use the SDK from a CDN:

import { Trulioo } from "https://cdn.trulioo.com/web/sdk/trulioo/latest/dist/esm/trulioo.js";

Use a pinned version instead of the latest package:

import { Trulioo } from "https://cdn.trulioo.com/web/sdk/trulioo/VERSION_NUMBER/dist/esm/trulioo.js";

Replace VERSION_NUMBER with the SDK version you want to lock to.

Before You Start

Before using the SDK, make sure the host application:

• has a valid shortcode generated through the Trulioo customer handoff flow using the Customer API 3.0 handoff operation
• uses a shortcode configured for Device Intelligence when required by the journey
• initializes a new SDK session for each verification journey

Initialization

Initialize once with the shortcode before starting a verification capability:

const initialized = await Trulioo.initialize(shortcode);

initialized is a TruliooInitializationResult for the current verification journey. Retain it only while that journey is active.

What Initialization Does

Initialization:

1. resolves the service host from the shortcode
2. establishes an authorized SDK session
3. retrieves the session configuration
4. when Device Intelligence is enabled, loads the managed device runtime
5. returns the initialization result for the current verification journey

Initialization Result

initialize(...) returns the current TruliooInitializationResult.

The SDK retains the session configuration, resolved service host, and authorization token internally for the active session. Call reset() to clear that session before starting another journey.

Verification Capabilities

Beta - changes are possible.

After initialization, start the capability required by the current verification journey. Availability is determined by the shortcode configuration.

Device Intelligence

Use Device Intelligence when the verification journey needs a device-risk result before deciding the next step.

Choose An Integration Mode

Recommended: collectDeviceIntelligence(...)

For most integrations, use collectDeviceIntelligence(...). It performs collection, submission, and polling in one Promise-based call. It returns a terminal event when processing completes or fails; if the configured polling limit is reached first, it returns the latest non-terminal lifecycle event and records the timeout in debugTrace.

If polling exhausts, the result contains the last non-terminal lifecycle state and debugTrace contains a device_event_terminal timeout entry. Wait and retrieve the detailed result only after the status is COMPLETED. If the event fails, use deviceEvent.failureReason for the failure detail.

1. initialize once
2. call collectDeviceIntelligence(...)
3. use a completed deviceEvent to continue the journey

Explicit collection example:

import { DeviceEventStatus, Trulioo } from "@trulioo/trulioo";

const initialized = await Trulioo.initialize(shortcode);

const result = await Trulioo.collectDeviceIntelligence();

if (result.deviceEvent?.status === DeviceEventStatus.Completed) {
  const { eventId, transactionId } = result.deviceEvent;
}

collectDeviceIntelligence(...) returns an enriched TruliooInitializationResult for the same session.

When deviceEvent.status is COMPLETED, use deviceEvent.transactionId to retrieve the detailed result. To retrieve the detailed result, see Retrieve the Detailed Result.

Background Submission: sendDeviceInformation(...)

Use sendDeviceInformation(...) when the application should submit DI without waiting for server evaluation or a final risk result.

import { Trulioo, TruliooSendDeviceInformationStatus } from "@trulioo/trulioo";

const initialized = await Trulioo.initialize(shortcode);

const submission = await Trulioo.sendDeviceInformation();

if (submission.status === TruliooSendDeviceInformationStatus.Accepted) {
  console.log(submission.transactionId, submission.eventId);
} else {
  console.error(submission.error.code, submission.error.message);
}

The submission result is one of two shapes.

Accepted Response Fields

Failed Response Fields

sendDeviceInformation(...) is designed for receipt-based background submission. It returns after Trulioo accepts the event, rather than waiting for a final DI outcome.

Neither DI integration mode returns the detailed device result. Use the returned transaction ID with Retrieve the Detailed Result after processing completes.

Retrieve the Detailed Result

Both integration modes provide transactionId after submission. Call GET /transactions/{transactionId}/devices with that value after device processing is complete to retrieve the detailed device result.

• collectDeviceIntelligence(...) normally resolves after reaching completed or failed. If its configured polling limit is reached first, it resolves with the latest non-terminal lifecycle state and records the timeout in debugTrace.
• sendDeviceInformation(...) returns accepted before evaluation completes.

Retrieve details after the event is completed. If collectDeviceIntelligence(...) returns a non-terminal status, wait and retry the endpoint until processing completes.

See Get transaction devices for authentication, request requirements, and the detailed result fields.

Device Intelligence Options

Device Intelligence options customize explicit DI collection. They are optional; the SDK manages the device runtime automatically.

collectDeviceIntelligence(...) accepts optional polling controls:

Provide options directly to explicit collection:

const result = await Trulioo.collectDeviceIntelligence({
  polling: {
    maxAttempts: 10,
    intervalMs: 1000,
  },
});

Resetting State

Call Trulioo.reset() to clear all internal session state. Use this for logout flows, multi-session apps, or when re-initializing with a new shortcode:

Trulioo.reset();
// Can now call Trulioo.initialize(...) again with a new shortcode

reset() clears the internally stored session. Reinitialize before starting another session, and do not reuse a previous initialization result after reset.

Error Handling

Initialization errors:

• reject the initialization promise

Send errors:

• resolve with { status: TruliooSendDeviceInformationStatus.Failed, error: { code, stage, message, debugTrace } }

Collection errors:

• resolve with the unchanged initialization result when Device Intelligence is not enabled for the session
• reject the collection promise when device-runtime initialization, payload submission, device-event seeding, or a polling request fails
• resolve with the latest lifecycle-only deviceEvent when polling reaches its limit before a terminal status; inspect the returned debugTrace for the timeout entry

Troubleshooting

If Device Intelligence does not appear:

1. Confirm initialization completed successfully.
2. Confirm Device Intelligence is enabled for the account and verification journey.
3. Confirm you explicitly called collectDeviceIntelligence(...) or sendDeviceInformation(...).
4. Inspect debugTrace.

If results are incomplete:

1. Inspect deviceEvent?.failureReason.
2. Inspect debugTrace for a polling timeout or failed stage.
3. After the event completes, retrieve the detailed result with GET /transactions/{transactionId}/devices.