Trulioo Android 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 Android SDK facilitates the capture of government-issued identity documents and biometrics for the purpose of identity verification.

Trulioo’ s sophisticated technology delivers a smooth experience for your end-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 allow you to seamlessly connect the image capture process into your own application 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

The SDK supports Android 6.0 (API level 24) and above (distribution stats).

The project must also have Java 8 enabled and use AndroidX. The Android SDK is designed around Kotlin and leverages asynchronous programming models for interactions and results.

Our configuration is currently set to the following:

minSdkVersion = 24
targetSdkVersion = 34
android.useAndroidX = true
Kotlin = 1.9.10+

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

1. Obtain a Transaction shortcode

In order to start your integrating, you will need an API token and REST API integration outside of the application. You will generate a Shortcode that lasts up to 5 minutes and provide the Shortcode to your application when ready to launch your Document Verification workflow.

Note: You must never use API tokens in the frontend of your application 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

The SDK is available on Maven.

The steps below assume that the user already has the Maven repository added to their project. You can include the SDK in your projects by adding the following to your root build.gradle file.

// build.gradle.kts
dependencies {
    implementation("com.trulioo:docv:2.+")
}

// build.gradle
dependencies {
    implementation 'com.trulioo.docv:2.+'
}

where 2.+ indicates a version greater than 2.0.0.

Save your changes to the project and build it. You should see com.trulioo.docv:2.+ added to your External Libraries.

3. Grant permissions

The SDK will request permissions as needed. Please make sure that the browser has CAMERA permissions enabled.

4. Start a verification flow

Create a new verification object using registerForActivityResult(Trulioo()), and call its launch() method with the workflow as a parameter to initialize the SDK.

val shortCode = "sample-short-code" // Set the obtained short code from the Trulioo Customer API
val workflow = TruliooWorkflow(shortCode)

lifecycleScope.launch {
    val activityLauncher =
        Trulioo().registerForActivityResult(this@Activity, workflow) {}

    if (activityLauncher is Success) {
        activityLauncher.value.launch(workflow)
    }
}

data class TruliooWorkflow(
    val shortCode: String,
    val locale: String? = null,
    val workflowTheme: WorkflowTheme? = null,
    val isDemo: Boolean = false,
    val enableRegionSelection: Boolean = true,
    val enableDocumentAutoCapture: Boolean = true
)

data class WorkflowTheme(
    val logoSource: String? = null,
    val primaryButtonColor: String? = null,
    val primaryButtonTextColor: String? = null
)

5. Getting a result

You can pass in a switch block to handle different results returned by registerForActivityResult(Trulioo()):

val activityLauncher = Trulioo().registerForActivityResult(this@Activity, workflow) { result ->
    when (result) {
        is TruliooResult.Complete -> println("Transaction ID: ${result.transactionId}")
        is TruliooResult.Error -> println("Error: ${result.code}, Reason: ${result.message}")
        is TruliooResult.Exception -> println("Exception: $result")
    }
}

Example Activity that launches Trulioo

class Activity : ComponentActivity() {

	override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val shortCode =
            "sample-short-code" // Set the obtained short code from the Trulioo Customer API
        val workflow = TruliooWorkflow(shortCode)

        lifecycleScope.launch {
            val activityLauncher = registerForActivityResult(Trulioo()) { result ->
                when (result) {
                    is TruliooResult.Complete -> println("Transaction ID: ${result.transactionId}")
                    is TruliooResult.Error -> println("Error: ${result.code}, Reason: ${result.message}")
                    is TruliooResult.Exception -> println("Exception: $result")
                }
            }
            if (activityLauncher is Success) {
                activityLauncher.value.launch(workflow)
            }
        }
    }
}

Changing 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 device 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 set language locale, pass in the desired language as a Locale ID (LCID) short string in the locale parameter of the TruliooWorkflow object.

// Find a list of supported locales (LCID) in the table below.
val workflow = TruliooWorkflow(shortCode = "sample-short-code", locale = "fr-CA")

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 +
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 +
Hindi	hi	2.5.0 +
Hungarian	hu	2.9.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 +
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

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

To use a custom theme, the SDK provides the WorkflowTheme object that allows for some customizations.

To set a desired logo for branding, you can pass in the ID of a drawable resource as a string in the logoSource parameter. The provided logo will be displayed with a fixed height of 32 pixels.

To customize the primary buttons colors, you can set the primaryButtonColor and primaryButtonTextColor parameters with hex color string values.

val workflowTheme = WorkflowTheme(logoSource = R.drawable.app_logo.toString(),
    primaryButtonColor = "#fcc9b9", primaryButtonTextColor = "#562135")
val workflow = TruliooWorkflow(shortCode = "sample-short-code", locale = "en-US", workflowTheme = workflowTheme)

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.
Change the parameter 'enableRegionSelection' to false and both screens will be hidden from the user.

TruliooWorkflow(
    shortCode = "sample-short-code",
    locale = "en-US",
    workflowTheme = null,
    isDemo = false,
    enableRegionSelection = true,
    enableDocumentAutoCapture = true
)

Handle the verification result

After a session is completed, callback functions are invoked based on the result of the workflow (see above code block for example):

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

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


val sessionResult = Trulioo().getSessionResult()
println("Transaction status: ${sessionResult.status}\nTransaction ID: ${sessionResult.transactionId}")

The result object should contain the Transaction ID and the verification status which could be one of the following:

Result	Description
`Accepted`	This is displayed when the verification result returns a pass result. The identity documentation is verified.
`Review`	The verification results will be flagged for review if there is insufficient information to run the verification test. Checks are run for the validity of the document type, and the quality of the data extracted via Optical Character Recognition.
`Declined`	Block fraudsters from your platform with automated rejection criteria. The declined result appears when the verification test returns a fail result and the identity documentation is not verified.
`Error`	When the verification test is not completed as expected, you’ll see what configuration or authorization issues to troubleshoot. The error message will also identify any missing or improperly captured image data.

Cancel a verification

It is recommended to complete a verification fully. However, if you wish to cancel an active verification flow, you can do so anytime by calling the close() method. This method will dismiss the SDK from the user’s device and TruliooResult.Error will be called to indicate that the verification has been interrupted. When you are ready to initiate a new verification, you can create a new workflow and launch the SDK again.

Note: using close() is usually not necessary as the SDK will internally call this method when the verification has completed.

Trulioo().close()

// TruliooResult.Error will trigger after Trulioo().close()
val activityLauncher = Trulioo().registerForActivityResult(this@Activity, workflow) { result ->
    when (result) {
        is TruliooResult.Complete -> println("Transaction ID: ${result.transactionId}")
        is TruliooResult.Error -> println("Error: ${result.code}, Reason: ${result.message}")
        is TruliooResult.Exception -> println("Exception: $result")
    }
}

Handling 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.
`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.