Trulioo KYC Documents SDK — Android

The KYC Documents SDK delivers a complete, Trulioo-designed document verification UI for Android. The SDK owns the full capture experience — your application launches it with a shortcode and handles the terminal result.

Need full UI control? If you want to design your own capture experience, see the KYC Documents Capture Android SDK instead.

Biometric Data Notice

Some US states impose obligations on businesses that collect biometric identifiers or biometric information, which may include facial scan data extracted during a document verification transaction. One such law is the Illinois Biometric Information Privacy Act (BIPA). Businesses subject to BIPA must inform individuals of the purpose of data collection and obtain their consent before proceeding.

Trulioo requires a notice and consent mechanism for all document verification transactions. Customers using our API must confirm via API whether an individual is located in the United States and has consented in the prescribed manner. We strongly encourage all customers to consult with legal counsel to ensure their own compliance.

For more information, refer to our Service Specific Terms for Document Verification.

Quick Start

1. Add the com.trulioo:kyc-documents dependency to your project.
2. Register Trulioo.LaunchKYCDocuments() with the Android activity-result API.
3. Get a shortcode from your backend for the active transaction.
4. Call launcher.launch(shortcode).
5. Handle the returned KYCDocumentsResult.

What This SDK Covers

The SDK owns the full document verification experience. Your application owns the launch trigger and the terminal result.

Package and Compatibility

The Android artifact is a fused AAR. You do not need to integrate the Capture SDK separately when using the hosted Docs flow.

Installation

dependencies {
    implementation("com.trulioo:kyc-documents:<version>")
}

UIKit Integration Example

import android.os.Bundle
import androidx.activity.ComponentActivity
import com.trulioo.docv.ui.KYCDocumentsResult
import com.trulioo.docv.ui.Trulioo

class DocsHostActivity : ComponentActivity() {
    private val docsLauncher =
        registerForActivityResult(Trulioo.LaunchKYCDocuments()) { result ->
            when (result) {
                is KYCDocumentsResult.Complete ->
                    println("Completed transaction: ${result.transactionId}")
                is KYCDocumentsResult.Error ->
                    println("Docs error: ${result.code} ${result.message}")
                is KYCDocumentsResult.Exception ->
                    println("Docs exception: ${result.exception.message}")
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        docsLauncher.launch("your-shortcode-here")
    }
}

Compose Integration Example

import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import com.trulioo.docv.ui.KYCDocumentsResult
import com.trulioo.docv.ui.Trulioo

@Composable
fun DocsLaunchButton(shortcode: String, onResult: (KYCDocumentsResult) -> Unit) {
    val launcher = rememberLauncherForActivityResult(
        contract = Trulioo.LaunchKYCDocuments(),
        onResult = onResult,
    )

    Button(onClick = { launcher.launch(shortcode) }) {
        Text("Start verification")
    }
}

How the Launch Flow Works

Calling launcher.launch(shortcode) triggers the full hosted flow:

1. The SDK-owned activity starts.
2. The active Docs transaction is authorized from the shortcode.
3. Transaction configuration is loaded for the hosted flow.
4. The SDK runs the hosted document and selfie capture experience.
5. KYCDocumentsResult is returned to your registered callback.

Your application does not create intents manually. Trulioo.LaunchKYCDocuments() owns intent creation and result normalization.

Handling Results

when (result) {
    is KYCDocumentsResult.Complete -> {
        // Terminal success — navigate to a success state
        println("Transaction ID: ${result.transactionId}")
    }
    is KYCDocumentsResult.Error -> {
        // Handled product failure — show a retry or failure state
        println("Error: ${result.code} ${result.message}")
    }
    is KYCDocumentsResult.Exception -> {
        // Cancellation or unexpected termination — log and recover the host UI
        println("Exception: ${result.exception.message}")
    }
}

Result types:

Activity.RESULT_CANCELED is normalized into KYCDocumentsResult.Exception. Treat this as cancellation, not a handled product error.

Customization

The Android Docs SDK does not expose a host-side theme or locale builder. These behaviors are controlled by the transaction associated with the shortcode:

• Locale and branding
• Available countries and document types
• Capture-step requirements
• Desktop-to-mobile enablement

To change these behaviors, update the transaction configuration in the Trulioo customer handoff flow.

Common Mistakes

Launching with a blank or stale shortcode. Always use a fresh shortcode generated for the active transaction. Do not reuse shortcodes across unrelated transactions.

Trying to embed camera UI directly. The Docs SDK owns its own Activity and the full capture experience. If you need to compose your own camera UI, use the KYC Documents Capture SDK instead.

Treating KYCDocumentsResult.Exception as a handled product error. Exception means the flow was cancelled or terminated unexpectedly — it is not the same as a structured Error result.

Building your own intent instead of using Trulioo.LaunchKYCDocuments(). The activity-result contract owns intent creation and result normalization. Do not bypass it.

Troubleshooting

The SDK returns an error immediately: Verify the shortcode is valid and belongs to the expected environment.

The SDK closes without a success result: Inspect whether the result is Error or Exception and log the details before deciding whether to retry.

No transaction ID in the result: Only KYCDocumentsResult.Complete guarantees a transaction ID. Error may include one when available, but Exception does not.

The host app sees unexpected cancellation: Activity.RESULT_CANCELED is normalized into KYCDocumentsResult.Exception. Check whether the user cancelled or whether a configuration or permission issue caused early termination.

Diagnostic Checklist

When filing a support issue, include:

• Docs SDK version.
• Device model and Android version.
• The shortcode environment used (production, development, preview).
• Whether the flow was pure mobile or desktop-to-mobile.
• The final KYCDocumentsResult type and payload.
• The transaction ID, if available.
• Whether a fresh shortcode was used before retrying.