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 and eID 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. start the required capability: Device Intelligence or eID
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 the capabilities required by the journey, such as Device Intelligence or eID
• 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,
  },
});

eID Verification

Use the eID entrypoints when your web flow needs an interactive provider-backed identity verification from the same initialized session.

Start a Verification

eID has one standard flow:

1. initialize once
2. call Trulioo.verifyEid(...) from the customer's continue action
3. inspect the terminal result

verifyEid(...) uses the session established by initialize(...). It prepares the provider session automatically when needed, opens the interactive provider flow, and waits for the backend result.

Call it directly from a user action. Browsers can block a provider popup or tab that is opened outside a user gesture.

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

const initialized = await Trulioo.initialize(shortcode);

try {
  const result = await Trulioo.verifyEid({
    countryCode: "CA",
  });

  if (result.outcome === "SUCCESS" && result.match) {
    console.log("eid verified", result.transactionId);
  } else {
    console.log("eid not verified", result);
  }
} catch (error) {
  // The provider flow could not complete, for example because the popup was
  // blocked, the customer cancelled, the flow timed out, or a request failed.
  console.error("eid verification failed", error);
}

Result

When the provider flow completes and backend polling produces a result, verifyEid(...) resolves with an EidVerificationResult. The result does not contain the customer's submitted identity data. Browser-flow, preparation, and network failures reject the promise instead.

Apply the host application's policy to the result. For example, continue after SUCCESS with match: true; provide a retry or alternate journey for other results and caught errors.

Retrieve the Detailed Result

After verifyEid(...) reaches a terminal result, call GET /transactions/{transactionId}/eid/result with result.transactionId to retrieve the detailed eID result.

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

Input

import type { EidVerificationConfig } from "@trulioo/trulioo";

const input: EidVerificationConfig = {
  countryCode: "CA",
  // providerIdentifier: "provider-id", // optional provider pin
};

Optional: Choosing a specific Provider

Provider discovery is optional. When providerIdentifier is omitted, Trulioo selects the healthiest licensed provider for the configured country. Call listEidProviders(...) only when the application needs to show a provider picker.

const providers = await Trulioo.listEidProviders("CA");

const result = await Trulioo.verifyEid({
  countryCode: "CA",
  providerIdentifier: providers[0]?.id,
});

To restart an interrupted eID flow, call Trulioo.reset() and initialize a new session.

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 and resets cached eID state. Reinitialize before starting another session.

Session-backed methods throw TruliooNotInitializedError after reset: listEidProviders(...) and verifyEid(...). Device Intelligence methods receive an explicit initialization result; do not reuse a previous result after reset—initialize again instead.

Error Handling

Not-initialized errors:

• TruliooNotInitializedError is thrown by session-backed methods when called before initialize() completes or after reset()
• Affected methods: listEidProviders and verifyEid.

Initialization errors:

• reject the initialization promise

Send errors:

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

eID errors:

• verifyEid(...) rejects when preparation, provider handoff, callback handling, or result polling fails
• It also rejects when the customer cancels, the provider flow times out, the browser blocks the popup, or another eID verification is already in progress

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.

If eID does not start or complete:

1. Confirm initialization completed successfully and the selected country is configured for eID.
2. Call verifyEid(...) directly from the customer's action so the browser can open the provider flow.
3. Inspect a resolved result's outcome and match, or handle the rejected error when the provider flow, callback, or result polling fails.
4. Call reset(), initialize a new session, then retry an interrupted eID flow.