Trulioo SDK - Android Guide

Quick Summary

The Trulioo Android SDK initializes a shortcode-backed session and exposes base verification capabilities for Android applications.

Customer applications can expect the SDK to:

• resolve session configuration and authorization from the active shortcode
• support configured Device Intelligence capabilities
• return Android-native results, identifiers, errors, and diagnostic trace data for host routing and support

On Android, a standard integration looks like this:

1. add the Trulioo Android dependency
2. ensure any release-specific runtime dependencies are present
3. make sure the SDK has access to Application
4. initialize with a shortcode
5. collect Device Intelligence when required by the journey
6. use the result to continue, retry, or route the journey for review

Package And Compatibility

• Maven artifact: com.trulioo:trulioo:<version>
• Kotlin package namespace: com.trulioo.sdk.android
• minimum Android SDK: 24

Some Trulioo Android releases require an additional runtime dependency. Use the exact dependency instructions published with the Trulioo release you are integrating.

Android-Specific Background

The Android device-intelligence path requires an Application instance.

The current Android host contract is:

• Application: required
• Activity: optional

This matters because the device-intelligence runtime is initialized using Application, not a short-lived UI context.

Installation

Gradle Dependency

dependencies {
    implementation("com.trulioo:trulioo:<version>")
    // Add any additional runtime dependency required by the Trulioo release instructions for this version.
}

Runtime Context Setup

By default, the SDK captures application context through AndroidX Startup.

That means most apps can use:

val hostContext = DeviceSdkHostContext.fromRuntime()

If your build disables manifest merging or AndroidX Startup, pass an explicit host context:

val hostContext = DeviceSdkHostContext(
    application = application,
    activity = activity,
)

Before You Start

Before using the SDK, make sure the host application:

• has a valid shortcode generated through the Trulioo customer handoff flow using the Customer API 3.0 handoff operation
• uses a shortcode configured for Device Intelligence when required by the journey
• initializes a new SDK session for each verification journey

Initialization

Initialization is callback-based:

Trulioo.initialize(
    shortcode = shortcode,
    onComplete = { result ->
        // Persist result for later collection
    },
    onError = { error ->
        // Initialization failed
    },
    hostContext = DeviceSdkHostContext.fromRuntime(),
)

What Initialization Does

Initialization:

1. resolves the service host from the shortcode
2. establishes an authorized SDK session
3. retrieves the session configuration
4. retains Device Intelligence configuration for later native collection when enabled
5. returns the initialization result for the current verification journey

Initialization Result

The onComplete callback receives the current TruliooInitializationResult.

The SDK retains the session configuration, resolved service host, and authorization token internally for the active session. Call reset() to clear that session before starting another journey.

Verification Capabilities

Beta - changes are possible.

Device Intelligence

Use Device Intelligence when your Android flow needs device-risk telemetry from the current app session.

Choose An Integration Mode

Recommended: collectDeviceIntelligence(...)

The normal Android sequence is:

1. initialize once
2. call collectDeviceIntelligence(...) when the host needs an explicit device result
3. inspect the lifecycle status and diagnostics

For most integrations, use collectDeviceIntelligence(...). It performs collection, submission, and polling in one suspend call. It returns a terminal event when processing completes or fails; if the configured polling limit is reached first, it returns the latest non-terminal lifecycle event and records the timeout in debugTrace.

If polling exhausts, the result contains the last non-terminal lifecycle state and debugTrace contains a device_event_terminal timeout entry. Wait and retrieve the detailed result only after the status is COMPLETED. If the event fails, use deviceEvent.failureReason for the failure detail.

Explicit collection example:

val result =
    Trulioo.collectDeviceIntelligence(
        hostContext = DeviceSdkHostContext.fromRuntime(),
        options =
            DeviceIntelligenceCollectionOptions(
                polling = DeviceIntelligencePollingOptions(),
            ),
    )

Log.d("Trulioo", "deviceEvent=${result.deviceEvent}")

collectDeviceIntelligence(...) returns an enriched TruliooInitializationResult for the same session.

Background Submission: sendDeviceInformation(...)

Use sendDeviceInformation(...) when the application should submit DI without waiting for server evaluation or a final risk result.

val submission =
    Trulioo.sendDeviceInformation(
        hostContext = DeviceSdkHostContext.fromRuntime(),
    )

It returns after Trulioo accepts the event, rather than waiting for a terminal DI outcome.

The submission result is one of two variants.

Accepted Response Fields

Failed Response Fields

Retrieve the Detailed Result

Both integration modes provide transactionId after submission. Call GET /transactions/{transactionId}/devices with that value after device processing is complete to retrieve the detailed device result.

• collectDeviceIntelligence(...) normally returns after reaching COMPLETED or FAILED. If its configured polling limit is reached first, it returns the latest non-terminal lifecycle state and records the timeout in debugTrace.
• sendDeviceInformation(...) returns after Trulioo accepts the event, before evaluation completes.

Retrieve details after the event is COMPLETED. If collectDeviceIntelligence(...) returns a non-terminal status, wait and retry the endpoint until processing completes.

See Get transaction devices for authentication, request requirements, and the detailed result fields.

Device Intelligence Options

Device Intelligence options customize explicit DI collection. They are optional; the SDK manages the device runtime automatically.

collectDeviceIntelligence(...) accepts optional polling controls:

Provide options directly to explicit collection:

val result =
    Trulioo.collectDeviceIntelligence(
        hostContext = DeviceSdkHostContext.fromRuntime(),
        options =
            DeviceIntelligenceCollectionOptions(
                polling =
                    DeviceIntelligencePollingOptions(
                        maxAttempts = 10,
                        intervalMs = 1000,
                    ),
            ),
    )

Resetting State

Call Trulioo.reset() to clear all internal session state. Use this for logout flows or before re-initializing with a new shortcode:

Trulioo.reset()
// Can now call Trulioo.initialize(...) again

Error Handling

Not-initialized errors:

• TruliooNotInitializedException is thrown when calling any method before initialize() completes or after reset()
• Affected method: collectDeviceIntelligence

Initialization errors are delivered through onError.

Send errors:

• return SendDeviceInformationResult.Failed with a stable failure code, stage, message, identifiers when known, and debugTrace

Device collection failures throw DeviceIntelligenceCollectionException. That exception includes the partial initializationResult, which is useful because it preserves debug trace data gathered before failure.

Troubleshooting

If Device Intelligence does not appear:

1. Confirm initialization completed successfully.
2. Confirm Device Intelligence is enabled for the account and verification journey.
3. Confirm you explicitly called collectDeviceIntelligence(...) or sendDeviceInformation(...).
4. Inspect debugTrace.

If results are incomplete:

1. Inspect deviceEvent?.failureReason.
2. Inspect debugTrace for a polling timeout or failed stage.
3. After the event completes, retrieve the detailed result with GET /transactions/{transactionId}/devices.