Android SDK

Integrate the TrustPlatform Android SDK into your Android app

Requirements

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

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

Add the following to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

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.

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))
        }
    }
}

DocIDV Handler (Optional)

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 for eID scanning are included automatically via manifest merging from the DocIDV handler's dependencies. No additional NFC entries are required in your manifest.

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 DocIDV step in the webview instead.