Android SDK

Integrate the TrustPlatform Android SDK into your Android app

This page covers the Android setup. For what the SDK does and how it fits into your integration, see the Mobile SDK overview.

Requirements

Requirement	Minimum version
Android API	24 (Android 7.0)
Kotlin	2.x

These are the Trust Platform SDK's requirements. If you add native document verification, the DocIDV SDK's requirements also apply.

Installation

1. Add the Maven repository

Add the following to your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://raw.githubusercontent.com/idnow/idnow-android-sdk/main") }
    }
}

2. Add the dependency

Use the BOM to keep module versions in sync:

// build.gradle.kts
dependencies {
    implementation(platform("io.idnow.trustplatform:bom:<version>"))
    implementation("io.idnow.trustplatform:core")
}

Register for Events

Call TrustPlatformSession.registerForResult in onCreate(), before the activity reaches onStart(). It takes one event handler and returns a session object that you use to launch and stop the SDK:

class MainActivity : ComponentActivity() {

    private lateinit var session: TrustPlatformLauncher

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

        session = TrustPlatformSession.registerForResult(this) { event ->
            when (event) {
                is TrustPlatformEvent.Progress -> { /* See Follow progress below. */ }
                is TrustPlatformEvent.Completed -> {
                    // The flow completed. Query your backend for the outcome.
                    // See https://docs.eu.platform.idnow.io/docs/integration/get-session-results
                }
                is TrustPlatformEvent.Aborted -> { /* The session was aborted on the server. This is final. */ }
                is TrustPlatformEvent.Dismissed -> { /* The SDK closed before the flow ended. The session keeps running. */ }
                is TrustPlatformEvent.Failed -> { /* event.error contains details */ }
            }
        }
    }
}

The handler runs on the main thread.

Configure the SDK

Pass a TrustPlatformEnvironment when you launch a session.

Environment	Description
`TrustPlatformEnvironment.Production`	The production environment
`TrustPlatformEnvironment.Sandbox`	The sandbox environment for development and testing (default)

Configure Permissions

The SDK declares INTERNET and ACCESS_NETWORK_STATE itself; both are merged into your app automatically. Check which device capabilities your flow needs, then add the matching permissions to your AndroidManifest.xml and request them at runtime before you launch a session:

Permission	Required for
`android.permission.CAMERA`	Document and biometric capture
`android.permission.RECORD_AUDIO`	Video-based verification steps, such as agent video calls

<uses-permission android:name="android.permission.CAMERA" />
<!-- Only if your flow includes video-based verification steps -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />

note

If the app has not been granted a permission, the SDK denies the matching camera or microphone request from the flow, and the step cannot capture.

NFC permissions for native document verification come with the DocIDV module. See native document verification.

Launch a Session

Create a session via the API, then launch the SDK with the session token:

session.launch(
    TrustPlatformConfig(
        token = token,
        environment = TrustPlatformEnvironment.Production,
    )
)

To close the SDK from your app, call session.stop(). See Close the SDK early.

Handle Events

The event handler receives progress while the flow runs, and then how the flow ended.

Event	When it occurs
`Progress(progress: StepProgress)`	The current step reports what it is waiting for. See Follow progress
`Completed`	The flow finished (the outcome might be accepted or rejected)
`Aborted`	The session was aborted on the server, for example because the user quit from the flow's own quit dialog or used up the retries the flow allows. This is final
`Dismissed`	The SDK closed before the flow ended, for example because the user pressed the back button. The session keeps running
`Failed(error: TrustPlatformError)`	The flow failed; `error` describes why

You receive any number of Progress events, then at most one of Completed, Aborted, Dismissed or Failed. Nothing follows it. If you close the SDK yourself with stop(), no terminal event is sent.

Completed only signals that the flow finished. To retrieve the actual outcome, query the Get session results API endpoint using the sessionId you received when creating the session. See Interpret session results for how to act on it. If the user returns after Aborted, start a new session.

TrustPlatformEvent is a closed set. event.error.message contains a machine-readable description suitable for logging. To display a localised, user-facing message, call event.error.errorDescription(context) instead.

is TrustPlatformEvent.Failed -> {
    Log.e(TAG, event.error.message ?: "Unknown error")
    showError(event.error.errorDescription(context))
}

Follow progress

Progress carries a StepProgress value that says what the current step is waiting for. The SDK reports progress, not steps: your app decides what to do about it.

session = TrustPlatformSession.registerForResult(this) { event ->
    when (event) {
        is TrustPlatformEvent.Progress -> when (event.progress) {
            // A review can take a while, so close the SDK and let your backend follow the session.
            StepProgress.InManualReview -> session.stop()
            else -> Unit // InProgress, EnduserInputNeeded, and values added later
        }
        // ... the other events
    }
}

StepProgress is an open set. Always keep an else branch, because more values will follow, and treat one you don't recognise as InProgress. The values, and which steps report more than InProgress, are described in Track step progress.

Progress is reported when the value changes, and short-lived values can be skipped. Progress can also be lost if Android recreates your activity while the SDK is on screen. If you must not miss a change, follow the session with step events on your backend.

Close the SDK early

Call session.stop() to close the SDK while the flow runs, for example from the InManualReview case above. It closes the SDK only: it does not end the session, and no event follows. Android has no equivalent of an await, so do anything your app needs after closing the SDK right after the stop() call, not in an event branch.

Closing the SDK is always your decision. The SDK doesn't know your user journey, so it never closes itself because of a progress value.

Run again

To open the SDK again for the same session, call launch again. This starts a new run on the device, with no memory of the previous one, and the session carries on from where it is. If the current step is already waiting when the run starts, you receive its progress value straight away, for example Progress(StepProgress.InManualReview) right after opening. Don't run two SDK instances for the same session at the same time: the second one is treated as a takeover from another device.

Native document verification (optional)

The trustplatform-docidv module runs document capture, and NFC chip reading where the flow uses it, as native screens instead of in the webview. It uses IDnow's DocIDV SDK, which the module brings in as a dependency; Maven resolves the matching version for you. Sessions, outcomes and data blocks are the same either way. See the Mobile SDK overview.

The DocIDV SDK's requirements apply when you add this module. For details specific to the DocIDV SDK, see the standalone DocIDV SDK documentation.

Add the Dependency

// build.gradle.kts
dependencies {
    implementation(platform("io.idnow.trustplatform:bom:<version>"))
    implementation("io.idnow.trustplatform:core")
    implementation("io.idnow.trustplatform:docidv")
}

note

NFC permissions are included automatically via manifest merging from the DocIDV module's dependencies. No additional NFC entries are required in your manifest.

NFC chip reading

NFC chip reading needs an additional dependency that is not available on Maven. Follow Integrate the NFC dependency in the DocIDV SDK documentation. NFC results are processed by the Verifying ID document (v3) step.

Packaging Configuration

trustplatform-docidv depends on BouncyCastle, which ships duplicate META-INF/LICENSE.md files across its JARs. Add the following packaging block to your android {} configuration to prevent a build error:

// build.gradle.kts
android {
    packaging {
        resources {
            pickFirsts += setOf(
                "META-INF/LICENSE.md",
                "META-INF/LICENSE-notice.md",
            )
        }
    }
}

How It Works

When you add trustplatform-docidv to your dependencies, the SDK discovers the DocIDV handler automatically at runtime via ServiceLoader — no registration call is required. If the dependency is absent, the SDK runs the document step in the webview instead.

Integrate the TrustPlatform Android SDK into your Android app​

Requirements​

Installation​

1. Add the Maven repository​

2. Add the dependency​

Register for Events​

Configure the SDK​

Configure Permissions​

Launch a Session​

Handle Events​

Follow progress​

Close the SDK early​

Run again​

Native document verification (optional)​

Add the Dependency​

NFC chip reading​

Packaging Configuration​

How It Works​