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.

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

There are two SDKs available: @trulioo/docv and @trulioo/docv-csp. The @trulioo/docv-csp is the same as the regular SDK but avoids inline style warnings if you are using the Content Security Policy tags in your website. Install the desired dependency via NPM or Yarn (you may need to adjust the path).

NPM

npm install @trulioo/docv 

or

npm install @trulioo/docv-csp 

Yarn

yarn add @trulioo/docv

or

yarn add @trulioo/docv-csp 

Import the node module:

import { Trulioo } from "@trulioo/docv"

or

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

For the @trulioo/docv-csp SDK, you will also need to import the css styling:

@import '@trulioo/docv-csp/main.css';

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, event} from "@trulioo/docv"

const elementID = "trulioo-sdk" // The HTML element id to attach to
const shortCode = "sample-short-code" // Set the obtained short code from step #1

// Set up the workflow configuration
const workflowOption = Trulioo.workflow()
     .setShortCode(shortCode)

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

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

// Initialize the SDK with the workflow configuration
Trulioo.initialize(workflowOption)
    .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)
    )

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

Locales are used to set the language of the SDK. This feature is available on version 2.5.0 or greater.

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, we provide a method on the SDK called setLanguage, this method accepts Locale ID (LCID) in the RFC5646 language format.
Some examples of an accepted locale format: "ar", "en-GB", "es-MX", "zh-Hans-CN".

The following lines should go after the import statement but before the callbacks setup.

// Find a list of supported locales (LCID) in the table below.
const shortCode = "sample-short-code" // Set the obtained short code from the Trulioo Customer API
const locale = "fr-CA" // Example of setting language locale to French (Canada).

const workflowOption = Trulioo.workflow()
     .setShortCode(shortCode)
     .setLanguage(locale)

Customize Theme

This customizing theme feature is available on version 2.5.0 or greater.

In order to customize some elements of the UI, the SDK provided the `WorkflowThemeBuilder`` that enables for some customization. The SDK currently supports three customizable elements:

• Logo: To set the desired logo or branding to be part of the UI, you can simply call setLogoSource. This method accepts a string representation of the
  image source which can be the url path to the hosted logo or a base64 format (Note: Currently, we only support base64 format for mobile only flow, hence it is recommended to provide the url path instead). The provided logo will be displayed with a fixed height of 32 pixels.

• Primary button background color: You can call setPrimaryButtonColor to set the button color.

• Primary button text color: You can call setPrimaryButtonTextColor to set the button text color.

The following lines should go after the import statement but before the callbacks setup.

const shortCode = "sample-short-code" // Set the obtained short code from the Trulioo Customer API

const workflowTheme = Trulioo.workflowTheme() // Create the WorkflowTheme object
     .setLogoSource("https://samplelogo.jpg")
     .setPrimaryButtonColor("#FF9800")
     .setPrimaryButtonTextColor("#007f5c")
     .build()

const workflowOption = Trulioo.workflow()
    .setShortCode(shortCode)
    .setTheme(workflowTheme) // Set the created WorkflowTheme object as part of the Workflow configuration 

Desktop to Mobile Workflow

The SDK also provides the ability for users to be able to capture documents using their mobile phone camera if they started the flow from the desktop browser.
When the user is on a desktop browser, they will be prompted with a QR Code to scan so they can continue their capture process using their mobile phone.
Once they finish the capture process, they will be redirected back to the desktop to finish their flow.

To enable Desktop to Mobile workflow, we provide a method on the SDK called setRedirectUrl. This method accepts a URL that hosts the Trulioo SDK, and can be the same instance of the SDK as is used for the Desktop flow. This means that, when the user scans the QR code, they will be redirected to the URL specified in setRedirectUrl (with query parameters appended to the end, see below).

Note that this means that you cannot setRedirectUrl to your localhost; you will need to serve localhost on a network that can be accessed by the phone scanning the QR code (e.g. the Internet). There are many tools available that can help you do this, such as ngrok.

The following lines should go after the import statement but before the callbacks setup.

const queryString = window.location.search
const urlParams = new URLSearchParams(queryString)
const shortCodeParam = urlParams.get("code") // Obtained the short code from the url param if there is any
const localeParam = urlParams.get("locale") // Obtained the locale from the url param if there is any
const host = "https://sample-url.com" // Set the QR Code redirect url host
    
let selectedShortCode = shortCodeParam // Use the obtained short code from the url param
    
if (shortCodeParam === null) {
    selectedShortCode = "sample-short-code" // Use the obtained short code from the Trulioo Customer API
}

const workflowOption = Trulioo.workflow()
    .setShortCode(selectedShortCode)
    .setRedirectUrl(host)

if (localeParam !== null) {
    workflowOption.setLanguage(localeParam) // Set the language locale provided from the url
}

In the codeblock above, the generated QR code will point to the URL redirect, appended with a query string code that is passed into the setShortCode call.

The code included in the query string indicates that it is coming from a desktop to mobile workflow. If there is no short code provided in a query string, then it will use the obtained short code provided from the Trulioo Customer API.

Additionally, in order to persist users' selected language locale from their desktop browser, the locale information will be passed as a query string of the QR code URL, which is later set on the workflow configuration.

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.
Same applies for the list of jurisdictions.

You can override the region selection screens and turn them off from the workflow builder.
Call the workflow builder function setRegionSelection(false) and both screens will be hidden from the user.

const workflowOption = Trulioo.workflow()
  .setRegionSelection(false)

Utilize the SDK from a CDN

In your project, you can import the Trulioo SDK:

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

or

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

If using @trulioo/docv-csp, also include the css style file into your html:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@trulioo/docv-csp/main.css">

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/docv@VERSION_NUMBER/+esm and replace the VERSION_NUMBER to your choice (this also applies to the @trulioo/docv-csp SDK and main.css file url).

Note: The cdn feature is only available after version 2.8.1 or above, any version below are not properly supported.

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):

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, the Transaction ID, and an errorCode
Any other exceptions will invoke the onException callback instead.

Additionally, you can utilize getSessionResult function call after completing the verification to get the result with the current result Transaction ID:

Trulioo.getSessionResult().then(result => {
    console.info(`Verification Result Status: ${result.status}, TransactionID: ${result.transactionId}`)
})

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

Handle verification errors