Migration Guide

This guide outlines the key changes and required updates when migrating your integration to the Trulioo KYC-Documents Javascript SDK (3.0).

1. Package Name Change

The SDK package has been renamed:

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

If you are using the CDN version:

- import truliooDocV from "https://cdn.jsdelivr.net/npm/@trulioo/docv/+esm"
+ import truliooKYC from "https://cdn.jsdelivr.net/npm/@trulioo/kyc-documents/+esm"

2. Configuration Management

Old Behaviour (2.x)

In v2, configurations were done directly in the SDK before initialization (e.g., .setShortCode, .setLanguage, .setTheme, .setRedirectUrl, etc.).

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

New Behaviour (3.0)

In v3, all workflow configuration is now handled via the Trulioo Configuration API. You only pass the short code into the SDK at initialization:

const trulioo = new Trulioo()
trulioo.initialize(shortCode)
    .then(complete => {
      trulioo.launch(elementID, callbackOption)
    })

🚧
Important: Any settings related to:

Language / locale

Theme customization (logos, colors)

Desktop-to-mobile workflow (redirects)

WebView support

Region selection

must now be configured through the Configuration API before generating the short code.

3. Event Handling Updates

Old Behaviour (2.x)

Events were set using Trulioo.event() and ListenerCallback:

const callbacks = new event.adapters.ListenerCallback({ ... })
const callbackOption = Trulioo.event().setCallbacks(callbacks)

New Behaviour (3.0)

Events are now managed through the EventBuilder:

const callbacks = new ListenerCallback({ ... })
const events = new EventBuilder()
const callbackOption = events.setCallbacks(callbacks)

4. Initialization and Launch

Old (2.x)

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

New (3.0)

const trulioo = new Trulioo()
trulioo.initialize(shortCode)
    .then(() => trulioo.launch(elementID, callbackOption))

5. CSS Imports

The SDK still automatically imports its required CSS. Ensure your bundler (e.g., webpack, vite) does not exclude CSS from node_modules.

6. CDN Usage

CDN usage remains the same, except for the package rename:

- https://cdn.jsdelivr.net/npm/@trulioo/docv@VERSION_NUMBER/+esm
+ https://cdn.jsdelivr.net/npm/@trulioo/kyc-documents@VERSION_NUMBER/+esm

7. Summary of Breaking Changes

Package renamed → @trulioo/kyc-documents
Configuration moved to API → SDK only needs shortCode
Events updated → Use EventBuilder instead of Trulioo.event()
Class instead of singleton object → From use directly Trulioo to create instance const trulioo = new Trulioo()
Initialization simplified → Pass shortCode directly to trulioo.initialize()
Deprecated methods removed:
- .setLanguage()
- .setTheme()
- .setRedirectUrl()
- .setWebView()
- .setRegionSelection()

Example Migration (Before → After)

v2.x

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

const workflowOption = Trulioo.workflow()
    .setShortCode("sample-short-code")
    .setLanguage("fr-CA")

const callbacks = new event.adapters.ListenerCallback({ ... })
const callbackOption = Trulioo.event().setCallbacks(callbacks)

Trulioo.initialize(workflowOption)
    .then(() => Trulioo.launch("trulioo-sdk", callbackOption))

v3.0

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

const shortCode = "sample-short-code"

const callbacks = new ListenerCallback({ ... })
const events = new EventBuilder()
const callbackOption = events.setCallbacks(callbacks)

const trulioo = new Trulioo()
trulioo.initialize(shortCode)
    .then(() => trulioo.launch("trulioo-sdk", callbackOption))