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

This guide covers the updates required to migrate 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 as its 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

What Changed At A Glance

Step 1: Replace The Package

Install the current package:

# Remove
npm uninstall @trulioo/docv

# Add
npm install @trulioo/kyc-documents

Update your imports:

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

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

Update CDN imports:

// 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.

Step 2: Remove The Workflow Builder

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

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

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

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 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(...); do not pass a 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, so your application does not need to configure it through JavaScript.

Result Handling

The callback categories are unchanged—onComplete, onError, and onException—but the flow now has 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 ListenerCallback surface as the primary terminal result mechanism.

Migration Checklist

• Replace @trulioo/docv with @trulioo/kyc-documents.
• Update the CDN import path from jsDelivr to cdn.trulioo.com when using 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(...) calls.
• 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.