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

This guide explains how to migrate a legacy DocV Web SDK integration from @trulioo/docv and @trulioo/docv-csp 2.x to @trulioo/kyc-documents 4.x.

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

• @trulioo/docv or @trulioo/docv-csp 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 @trulioo/docv-csp

# Add
npm install @trulioo/kyc-documents

For an npm integration, import the SDK stylesheet once from the application entry file:

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

Your bundler must support CSS imports. Import the stylesheet once; do not import it for every SDK launch.

Step 2: Update CDN Imports

Replace the legacy jsDelivr module with matching Trulioo CDN stylesheet and JavaScript module URLs. Pin both assets to the same version in production:

<!-- Before -->
<script type="module">
  import truliooDocV from "https://cdn.jsdelivr.net/npm/@trulioo/docv/+esm";
</script>

<!-- After -->
<link
  rel="stylesheet"
  href="https://cdn.trulioo.com/web/sdk/kyc-documents/VERSION_NUMBER/main.css"
/>
<script type="module">
  import {
    Trulioo,
    EventBuilder,
    ListenerCallback,
  } from "https://cdn.trulioo.com/web/sdk/kyc-documents/VERSION_NUMBER/kyc-documents.mjs";
</script>

Replace VERSION_NUMBER with the 4.x release you deploy. Load main.css before the SDK module.

Step 3: 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 4: Update Event Configuration

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

// Before: use the package your 2.x integration currently uses
import { Trulioo, event } from "@trulioo/docv";
// or
import { Trulioo, event } from "@trulioo/docv-csp";

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 5: 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: 4.x

import "@trulioo/kyc-documents/styles";
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 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 or @trulioo/docv-csp with @trulioo/kyc-documents 4.x or later.
• Import @trulioo/kyc-documents/styles once from the npm application entry file, or load the matching CDN main.css before the JavaScript module.
• Pin the CDN JavaScript module and stylesheet to the same version in production.
• 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.
• Verify the SDK UI renders correctly in the production build.