Trulioo Web SDK

📘
Info
Some US states impose obligations on businesses that collect and use “biometric identifiers” and/or “biometric information”, which may include facial scan data extracted from photos during a document verification transaction. One such law is the Illinois Biometric Information Privacy Act (“BIPA”). A business required to comply with BIPA is under obligations to, among other things, ensure that it informs the individual of the purpose of the collection and obtain consent. Accordingly, we require a notice and consent mechanism be implemented for all document verification transactions, and our customers using our API must provide us with confirmation via API whether an individual is located in the United States and has consented to the transaction in the prescribed manner. We also strongly encourage all of our customers to consult with legal counsel to ensure their own compliance with such laws.
For more information about the required notice and consent mechanism, please refer to our Service Specific Terms for Document Verification.

Overview

The Trulioo Web SDK provides components for JavaScript applications to facilitate the capture of government-issued identity documents and biometrics to use for identity verification.

Trulioo’s sophisticated technology delivers a smooth experience for your users, while optimizing for fast and accurate verification.

The intuitive UI/UX guides your users through the entire photo capture process
The modular app design allows you to seamlessly connect the image capture process into your own application's flow
Advanced image quality detection leads to higher verification success rates
Direct image upload to the Trulioo service simplifies integration

Note: The SDK is only responsible for capturing and uploading photos. Access the Trulioo Customer API for authorization and to perform checks.

Compatibility

To use the DocV SDK with the Customer API, please align the versions according to the below compatibility chart.

DocV SDK Version	Customer API Version
2.6.0 and above	2.4.0 and above
2.0.0 - 2.5.0	2.0.0 - 2.4.0

Getting started

All major browsers are supported for mobile image capture.


Latest ✔	Latest ✔	Latest ✔	Latest ✔

1. Obtain a Transaction short code through Trulioo API

In order to start integrating, you will need an API token and REST API integration outside of the application. You can reference our API's Getting Started guide and follow steps #1 and #2 to authorize and generate a shortCode. The shortcode lasts up to 5 minutes and should be supplied to your application before you launch your Document Verification workflow.

Note: You must never use API tokens in the frontend of your application in production, or malicious users could discover them in your source code. You should only use them on your server.

2. Download and install the Trulioo SDK

NPM

npm install @trulioo/kyc-documents

Yarn

yarn add @trulioo/kyc-documents

Import the node module:

import { Trulioo } from "@trulioo/kyc-documents"

3. Start a verification flow

The following code block creates a new workflow and launches the SDK:

Note that all code should be in JavaScript and not TypeScript.

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

const elementID = "trulioo-sdk" // The HTML element id to attach to
const shortCode = "sample-short-code" // Set the obtained short code from the Trulioo Customer API

// Set up callbacks to get results and debugging errors
const callbacks = new ListenerCallback({
    onComplete: (success: Response.Success) => {
        console.info(`Verification Successful: ${success.transactionId} `)
    },
    onError: (error: Response.Error) => {
        console.error(`Verification Failed with Error Code: ${error.code}, Reason: ${error.message}`)
    },
    onException: (exception: Response.Exception) => {
        console.error("Verification Failed with Exception:", exception)
    }
})

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

// Initialize the SDK with the shortcode
const trulioo = new Trulioo()
trulioo.initialize(shortCode)
    .then(complete => {
        console.info("Initialize complete:", complete)
        // Launch the UI with the provided HTML element ID
        trulioo.launch(elementID, callbackOption)
            .then(success => {
                console.info("Launch success:", success)
            })
    })
    .catch(error =>
        console.error("Error:", error)
    )

Note: The SDK will import additional css files automatically. Be sure to not exclude the css files contained in the @trulioo/kyc-documents node_modules directory from your web app configuration if you are using webpack css-loader or something similar.

4. Test the SDK

When using the SDK, it will request permissions from users as needed. It will require your users' browser CAMERA permissions to be enabled. The SDK provides its own messaging when the permissions are rejected, but you may want to do this on your end as well.

Change Language Locale

The SDK will default to the user's browser setting language locale.

If the given language is available but the given locale is not supported, the SDK will set to the given language and the default supported locale.

If the given language locale is not supported, the SDK will default to English (US).

To change the preferred language locale, use the locale field (an ENUM) available in the /sdk object of the Configuration API

Supported Languages & Locales

The SDK uses ISO 639-1 2-letter codes for specifying languages. When necessary, a 2-letter ISO 3166 country code is also included to specify regional language variations.

Language	Locale (LCID)	Support
Arabic	ar	2.5.0 +
Bengali	bn	2.5.0 +
Bulgarian	bg	2.9.0 +
Chinese (Hong Kong)	zh-HK	2.5.0 +
Chinese (Simplified)	zh-Hans-CN	2.5.0 +
Chinese (Traditional)	zh-Hant-TW	2.5.0 +
Czech	cs	2.9.0 +
Danish	da	2.9.0 +
Dutch (Netherlands)	nl-NL	2.5.0 +
English (United Kingdom)	en-GB	2.5.0 +
English (United States)	en-US	2.5.0 +
English (Canada)	en-CA	3.0.0 +
Estonian	et	2.9.0 +
Finnish	fi	2.9.0 +
French (Canada)	fr-CA	2.5.0 +
French (France)	fr-FR	2.5.0 +
German (Germany)	de-DE	2.5.0 +
Greek	el	2.9.0 +
Gujarati	gu	2.5.0 +
Hebrew	he	3.0.0 +
Hindi	hi	2.5.0 +
Hungarian	hu	2.9.0 +
Indonesia	id	3.0.0 +
Italian (Italy)	it-IT	2.5.0 +
Japanese	ja	2.5.0 +
Kannada	kn	2.5.0 +
Korean	ko	2.5.0 +
Lithuanian	lt	2.9.0 +
Malayalam	ml	2.5.0 +
Marathi	mr	2.5.0 +
Norwegian	no	2.9.0 +
Polish	pl	2.5.0 +
Portuguese (Brazil)	pt-BR	2.5.0 +
Portuguese (Portugal)	pt-PT	2.9.0 +
Romanian	ro	2.9.0 +
Russian	ru	2.5.0 +
Slovak	sk	2.9.0 +
Slovenian	sl	2.9.0 +
Spanish (Latin America)	es-MX	2.5.0 +
Spanish (Spain)	es-ES	3.0.0 +
Swedish	sv	2.5.0 +
Tamil	ta	2.5.0 +
Telugu	te	2.5.0 +
Thai	th	2.5.0 +
Turkish	tr	2.5.0 +
Ukrainian	uk	2.5.0 +
Vietnamese	vi	2.5.0 +

Customize Theme

The SDK supports customization options that allow you to tailor the user experience. You can configure settings such as language locale and themes. All customization is managed through the theme object within the /sdk object of the Configuration API when creating a transaction. Once the short code is provided to the SDK, it automatically renders using the configured locale and theme.

Desktop to Mobile Workflow

The SDK allows users to capture documents with their mobile phone camera even if they initiated the flow from a desktop browser. When a user begins the flow on a desktop browser, they are prompted with a QR code that enables them to continue the capture process on their mobile device. After completing the capture process on mobile, they are redirected back to the desktop to finish the flow.

To enable the Desktop to Mobile workflow, set setRedirectUrl within the /sdk object of the Configuration API.

Note that you cannot set redirectLink to a localhost address. You must serve your local environment on a network accessible to the mobile device scanning the QR code, such as via the public internet. Tools like ngrok can assist with this.

Enable WebView Support

The DocV Web Application can be accessed through WebView on both iOS and Android native apps. To configure WebView access, please see the sections below.

Ensuring iOS WebView Support

The DocV Web Appilcation requires camera permissions. Ensure the following keys are included in your iOS apps info.plist

<key>NSCameraUsageDescription</key>
<string>To validate your identity, camera access is required.</string>

When creating a WKWebView in your iOS Application, the camera feed must be streamed inline. This can be done by adjusting your WKWebView's WKWebViewConfiguration to use inline media playback.

webView = {
    let configuration = WKWebViewConfiguration()
    configuration.allowsInlineMediaPlayback = true
    let webView = WKWebView(frame: .zero, configuration: configuration)
    return webView
}()

Ensuring Android WebView Support

The DocV Web Appilcation requires camera and internet permissions. Ensure the following keys are included in the Android Manifest AndroidManifest.xml.

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET"/>

During the flow of the application, the user must be asked for camera permission Manifest.permission.CAMERA before starting the WebView.

val permission = arrayOf(android.Manifest.permission.CAMERA)
val requestCode = 1
ActivityCompat.requestPermissions(this, arrayOf(CAMERA), requestCode)

Finally, after the webView has been created, initialize the webView.webChromeClient with the below settings:

webView.webChromeClient = object : WebChromeClient() {
    // This override passes camera permissions from app level to webView
    override fun onPermissionRequest(request: PermissionRequest) {
        val requestedResource = request.resources
        for (resource in requestedResource) {
            if (resource.equals(RESOURCE_VIDEO_CAPTURE)) {
                request.grant(arrayOf(resource))
            }
        }
    }
}

 webView.apply {
    settings.javaScriptEnabled = true    
    settings.javaScriptCanOpenWindowsAutomatically = true
    settings.domStorageEnabled = true
    settings.allowContentAccess = true
    settings.mediaPlaybackRequiresUserGesture = false  
}

Country and Jurisdiction Selection

Each experience can be customized with specific countries and jurisdictions for each document type.

Use the API endpoint /customer/transactions to configure all the regions you accept. Please see here for more details on the API reference.

Note: If you specify an empty list for countries OR specify all supported countries, the country list will not appear. The sis ame applies for the list of jurisdictions.

You can override the region selection screens and disable them by using the countrySelectionEnabled and jurisdictionSelectionEnabled fields in the Configuration API.

Utilize the SDK from a CDN

In your project, you can import the Trulioo SDK:

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

You will now have full access to the SDK via your import, without any extra configuration steps needed.

The above URL will get you the latest version of the SDK. If you want to use a more specific version for the SDK, you can do https://cdn.jsdelivr.net/npm/@trulioo/kyc-documents@VERSION_NUMBER/+esm and replace the VERSION_NUMBER to your choice.

Handle the verification result

After a session is completed, callback functions are invoked based on the result of the workflow (see the codeblock from step #3 for examples of usage):

Callback	Notes
`onComplete`	User completed the flow. The `success` object contains the Transaction ID that can be used by the API to gain further insights.
`onError`	A user error has occurred. Some images may have already been uploaded. The `error` object contains information about the reason and an `errorCode`.
`onException`	An unexpected exception occurred.

When the user reaches the last screen of the flow and clicks on the "Continue" button to complete the flow, the user will be returned to the main application and the onComplete callback function will be invoked. The onComplete callback will return the success object, which contains the Transaction ID that can be used by the API to gain further insights. This applies for both the Mobile-only and Desktop-to-Mobile flows.

If any errors occurred during the verification flow, the onError callback will be invoked and it will return the error object that contains information with the reason for the error and an errorCode Any other exceptions will invoke the onException callback instead.

The result object will contain the Transaction ID and the verification status. The status can be one of the following:

Handle verification errors

Code	Description
`1010`	Workflow object does not contain a value for shortcode.
`1020`	Workflow object contains an invalid shortcode.
`1030`	The session does not contain a valid access token.
`1040`	The session was refreshed with an invalid short code.
`1210`	Workflow object does not have a valid redirect URL.
`1230`	There was a problem retrieving QR Code information.
`1320`	There was a problem on verification session creation.
`1330`	There was a problem submitting your session for verification.
`12020`	There was a problem retrieving custom configurations.