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 Results

Call TrustPlatformSession.registerForResult in onCreate(), before the activity reaches onStart():

class MainActivity : ComponentActivity() {

    private lateinit var launcher: ActivityResultLauncher<TrustPlatformConfig>

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

        launcher = TrustPlatformSession.registerForResult(this) { result ->
            when (result) {
                is TrustPlatformResult.Completed -> {
                    // The flow completed. Query your backend for the outcome.
                    // See https://docs.eu.platform.idnow.io/docs/integration/get-session-results
                }
                is TrustPlatformResult.Cancelled -> { /* user cancelled */ }
                is TrustPlatformResult.Failed    -> { /* result.error contains details */ }
            }
        }
    }
}

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:

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

Handle Results

Variant	When it occurs
Completed	The user completed the verification flow
Cancelled	The user cancelled the flow
Failed(error: TrustPlatformError)	The flow failed; error describes why

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.

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

launcher = TrustPlatformSession.registerForResult(this) { result ->
    when (result) {
        is TrustPlatformResult.Completed -> {
            // The flow completed. Query your backend for the outcome.
            // See https://docs.eu.platform.idnow.io/docs/integration/get-session-results
        }
        is TrustPlatformResult.Cancelled -> { /* user cancelled the flow */ }
        is TrustPlatformResult.Failed    -> {
            Log.e(TAG, result.error.message ?: "Unknown error")
            showError(result.error.errorDescription(context))
        }
    }
}

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.