Migration Guide - Docv 2.x to KYC Documents Web SDK

This guide covers everything you need to update when migrating from the legacy DocV Web SDK to the current Trulioo KYC Documents Web SDK.

Use this guide if your integration uses any of the following:

• @trulioo/docv or @trulioo/docv-csp as your npm package
• Trulioo.workflow() to configure the launch
• Trulioo.initialize(workflowOption) or Trulioo.launch(elementId, callbackOption)
• Host-side workflow methods such as setLanguage, setTheme, setRedirectUrl, setWebView, or setRegionSelection

Whats Changed: At a Glance

Step 1: Replace the Package

npm

# Remove
npm uninstall @trulioo/docv @trulioo/docv-csp

# Add
npm install @trulioo/kyc-documents

Update your import:

// Before
import { Trulioo } from "@trulioo/docv";
// or
import { Trulioo } from "@trulioo/docv-csp";

// After
import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "@trulioo/kyc-documents";

CDN

Update the import path:

// Before
import truliooDocV from "https://cdn.jsdelivr.net/npm/@trulioo/docv/+esm";

// After (latest)
import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "https://cdn.trulioo.com/web/sdk/kyc-documents/latest/kyc-documents.mjs";

// After (pinned version - recommended for production)
import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "https://cdn.trulioo.com/web/sdk/kyc-documents/VERSION_NUMBER/kyc-documents.mjs";

Replace VERSION_NUMBER with the release you want to lock to.

CSS: You no longer need a separate @trulioo/docv-csp package or a manual CSS import. The current package includes required styles automatically. If your existing integration has CSP-specific handling that depended on the old package name, review that setup carefully during migration.

Step 2: Remove the Workflow Builder

Trulioo.workflow() and all its chained methods have been removed. Delete any workflow-builder usage from your host app:

// Remove this entirely
const workflowOption = Trulioo.workflow()
  .setShortCode(shortCode)
  .setLanguage("fr-CA")
  .setTheme(workflowTheme)
  .setRedirectUrl("https://sample-url.com")
  .setWebView(true)
  .setRegionSelection(false);

Settings that were previously passed through the workflow builder - locale, theme, desktop-to-mobile redirect, region selection, and capture behavior - are now resolved from the transaction configuration on your backend. Move these settings to the backend flow that generates the shortcode.

Removed Workflow Methods

Step 3: Update Event Configuration

Replace the legacy static event namespace with EventBuilder and the top-level ListenerCallback:

// Before
import { Trulioo, event } from "@trulioo/docv";

const callbacks = new event.adapters.ListenerCallback({
  onComplete(success) { console.info(success.transactionId); },
  onError(error) { console.error(error.code, error.message); },
  onException(exception) { console.error(exception); },
});

const callbackOption = Trulioo.event().setCallbacks(callbacks);

// After
import { EventBuilder, ListenerCallback } from "@trulioo/kyc-documents";

const callbacks = new ListenerCallback({
  onComplete(success) { console.info(success.transactionId); },
  onError(error) { console.error(error.code, error.message); },
  onException(exception) { console.error(exception.message); },
});

const events = new EventBuilder().setCallbacks(callbacks);

The three callback categories - onComplete, onError, and onException - are unchanged.

Step 4: Update Initialization and Launch

Replace the static-style SDK calls with the instance-based pattern:

// Before
Trulioo.initialize(workflowOption)
  .then(() => Trulioo.launch(elementId, callbackOption));

// After
const trulioo = new Trulioo();

trulioo
  .initialize(shortCode)
  .then(() => trulioo.launch(elementId, events));

Key differences:

• Create a Trulioo instance with new Trulioo(); static calls are no longer used.
• Pass the shortcode string directly to initialize(...); there is no workflow object.
• Call launch(parentId, eventBuilder) on the same instance.

End-to-End: Before and After

Before (2.x)

import { Trulioo, event } from "@trulioo/docv";

const elementId = "trulioo-sdk";
const shortCode = "sample-short-code";

const workflowOption = Trulioo.workflow()
  .setShortCode(shortCode)
  .setLanguage("fr-CA");

const callbacks = new event.adapters.ListenerCallback({
  onComplete(success) { console.info(success.transactionId); },
  onError(error) { console.error(error.code, error.message); },
  onException(exception) { console.error(exception); },
});

const callbackOption = Trulioo.event().setCallbacks(callbacks);

Trulioo.initialize(workflowOption)
  .then(() => Trulioo.launch(elementId, callbackOption));

After (Current)

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "@trulioo/kyc-documents";

const elementId = "trulioo-sdk";
const shortCode = "sample-short-code";

const callbacks = new ListenerCallback({
  onComplete(success) { console.info(success.transactionId); },
  onError(error) { console.error(error.code, error.message); },
  onException(exception) { console.error(exception.message); },
});

const events = new EventBuilder().setCallbacks(callbacks);
const trulioo = new Trulioo();

trulioo
  .initialize(shortCode)
  .then(() => trulioo.launch(elementId, events));

Desktop-to-Mobile

If your 2.x integration used setRedirectUrl(...) or manually propagated locale or shortcode query parameters for the old workflow builder, remove that host-side setup.

Desktop-to-mobile behavior is now driven by the transaction configuration behind the shortcode. The SDK owns the hosted handoff flow; your application does not need to configure it through JavaScript.

Result Handling

The callback categories are unchanged (onComplete, onError, and onException), but the flow is now split into two stages:

1. initialize(shortCode) resolves authorization for the transaction.
2. launch(parentId, eventBuilder) attaches the hosted UI; callbacks receive terminal flow results.

getSessionResult() is not part of the current public web contract. Treat the TruliooCallbacks surface as the primary terminal result mechanism.

Migration Checklist

• Replace @trulioo/docv and @trulioo/docv-csp with @trulioo/kyc-documents.
• Update the CDN import path from jsDelivr to cdn.trulioo.com if you use CDN delivery.
• Remove Trulioo.workflow() and all workflow-builder method calls.
• Replace Trulioo.event() with new EventBuilder().
• Replace event.adapters.ListenerCallback with the top-level ListenerCallback.
• Replace Trulioo.initialize(workflowOption) with trulioo.initialize(shortCode).
• Replace static Trulioo.launch(...) calls with instance-based trulioo.launch(...).
• Move locale, theme, desktop-to-mobile, and region-selection settings to backend transaction configuration.
• Remove any getSessionResult() usage from the hosted web UI integration path.
• Remove any manual CSS imports or @trulioo/docv-csp handling; CSS is now included automatically.