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 and eID 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. start the required capability: Device Intelligence or eID
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 the capabilities required by the journey, such as Device Intelligence or eID
• 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,
                    ),
            ),
    )

eID Verification

Use the eID entrypoints when your Android flow needs an interactive provider-backed identity verification from the same initialized session.

Android Setup

Before starting an eID journey, complete both setup steps:

1. Register Auth Tab support once in the host ComponentActivity. The SDK uses Chrome Auth Tab when available and falls back to Chrome Custom Tabs otherwise.
2. Register the callback scheme in the app manifest. The provider redirects to this scheme when the customer finishes, and the SDK's redirect activity receives the callback.

Start a Verification

The normal Android sequence is:

1. initialize once
2. optionally call Trulioo.listEidProviders(...) to show a provider picker
3. call Trulioo.verifyEid(...) when the customer continues
4. inspect the terminal result; call Trulioo.reset() and initialize a new session before retrying

verifyEid(...) opens a system browser-authentication flow, rather than an embedded WebView. The SDK receives the callback and waits for the backend result.

Activity setup:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Trulioo.registerEidAuthTab(this)
    }
}

Use a globally unique callback scheme and declare it on EidRedirectActivity in AndroidManifest.xml:

<activity
    android:name="com.trulioo.sdk.android.eid.EidRedirectActivity"
    android:exported="true"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="com.example.app.eid" />
    </intent-filter>
</activity>

Pass the same value as callbackScheme when creating EidVerificationConfig.

Verification example:

lifecycleScope.launch {
    val config =
        EidVerificationConfig(
            countryCode = "SE",
            callbackScheme = "com.example.app.eid",
        )

    try {
        val result =
            Trulioo.verifyEid(
                activity = this@MainActivity,
                config = config,
            )

        if (result.outcome == EidOutcome.SUCCESS && result.match) {
            Log.d("Trulioo", "eid verified ${result.transactionId}")
        } else {
            Log.d("Trulioo", "eid not verified $result")
        }
    } catch (error: Exception) {
        // The provider flow could not complete, for example because the customer
        // cancelled, the flow timed out, or a request failed.
        Log.e("Trulioo", "eid verification failed", error)
    }
}

Result

verifyEid(...) returns after the provider flow and result polling reach a terminal result. The result does not contain the customer's submitted identity data.

Apply the host application's policy to the result. For example, continue after SUCCESS with match: true; provide a retry or alternate journey for other results and caught errors.

Retrieve the Detailed Result

After verifyEid(...) reaches a terminal result, call GET /transactions/{transactionId}/eid/result with result.transactionId to retrieve the detailed eID result.

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

Input

Optional: Choosing a specific Provider

Provider discovery is optional. When providerIdentifier is omitted, Trulioo selects the healthiest licensed provider for the configured country. Call listEidProviders(...) only when the application needs to show a provider picker.

val providers = Trulioo.listEidProviders(countryCode = "SE")

val config =
    EidVerificationConfig(
        countryCode = "SE",
        providerIdentifier = providers.firstOrNull()?.id,
        callbackScheme = "com.example.app.eid",
    )

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

Note: Calling listEidProviders or verifyEid after reset (without re-initializing) will throw TruliooNotInitializedException.

reset() also clears SDK-owned eID state.

Error Handling

Not-initialized errors:

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

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.

eID errors:

• verifyEid(...) throws when preparation, provider handoff, callback handling, or result polling fails
• verifyEid(...) also throws when the customer cancels, the provider flow times out, or another eID verification is already in progress

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.

If eID does not start or complete:

1. Confirm initialization completed successfully and the selected country is configured for eID.
2. Confirm registerEidAuthTab(...) was called during the host activity setup when using Auth Tab.
3. Call verifyEid(...) from the customer's action so Android can open the provider authentication flow.
4. Inspect a returned result's outcome and match, or handle the thrown error when provider handoff, callback handling, or result polling fails.
5. Call reset(), initialize a new session, then retry an interrupted eID flow.