Android SDK

A lightweight, server-driven Android SDK for identity verification with minimal configuration required.

GitHub Repository

View source code and examples on GitHub

Native SDK: This is the recommended approach for Android apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.

Requirements

Requirement	Minimum Version
Android API	23+ (Android 6.0 Marshmallow). ML auto-detection requires API 24+ (see below).
Kotlin	1.9+
Jetpack Compose	Included as a transitive dependency

Feature availability by API level: Document and face auto-detection use MediaPipe (API 24+). On API 23 devices the SDK falls back to manual capture with a timed shutter button. All other features work across the full API 23+ range.

Installation

Step 1: Add the Repository

Add the Didit Maven repository to the repositories block in your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository") }
    }
}

Or if using settings.gradle (Groovy):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository" }
    }
}

Step 2: Add the Dependency

Add the SDK dependency to your app’s build.gradle.kts: (!) Regarding the version ensure you check the GitHub repository for the latest version.

dependencies {
    implementation("me.didit:didit-sdk:4.6.0")
}

Or if using build.gradle (Groovy):

dependencies {
    implementation "me.didit:didit-sdk:4.6.0"
}

SDK variants

The Android SDK ships as four separate artifacts, so your app only pays the binary cost of the features it uses. me.didit:didit-sdk above is the full bundle. Pick exactly one:

Artifact	Auto-detection (ML)	NFC chip reading	Use when
`me.didit:didit-sdk-core`	–	–	smallest build; manual document capture only
`me.didit:didit-sdk-autodetection`	✓	–	auto capture, no passport/ID chip reading
`me.didit:didit-sdk-nfc`	–	✓	chip reading without the ML auto-capture runtime
`me.didit:didit-sdk`	✓	✓	every feature (full bundle)

Since 4.6.0, native WalletConnect wallet-signing ships as its own optional add-on, me.didit:didit-sdk-wallet. The full me.didit:didit-sdk bundle already includes it, so nothing changes if you install the bundle. If you use one of the slimmer artifacts and want wallet-ownership confirmation to run natively inside your app, add me.didit:didit-sdk-wallet next to it; without the add-on the SDK completes wallet ownership through a secure browser flow instead, so the feature keeps working either way. Moving WalletConnect out of didit-sdk-core also removed several megabytes of wallet dependencies from every build that does not need them. All artifacts are published at the same version, so keep them on 4.6.0.

Keeping the download small

The detection models used for auto-capture are downloaded at runtime and cached, so they never count against your app’s size. What auto-capture adds to your app is the ML runtime’s native library, and that cost is per CPU architecture: roughly 10 MB for arm64-v8a, 7 MB for armeabi-v7a, and 13 MB for each of the two x86 emulator architectures. To pay that cost only once:

Publish an Android App Bundle (AAB). Google Play delivers only the device’s own architecture and languages, so an arm64 phone installs roughly 10 MB of native code (about 4 MB of compressed download). A universal APK instead packs all four architectures — over 40 MB — which is the most common cause of unexpectedly large size measurements.
If you distribute a single APK and your audience is ARM phones and tablets, restrict the bundled architectures:
android { defaultConfig { ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") } } }
Keep every ABI your users actually run — add x86_64 if you target Chromebooks or other x86 devices, or publish per-ABI APK splits so no device loses support.
Enable R8 — isMinifyEnabled = true and isShrinkResources = true in your release build type (minifyEnabled true / shrinkResources true if you use Groovy build.gradle). The SDK ships its own consumer rules, so unused SDK code is stripped with no extra configuration.
Limit bundled languages with resConfigs(...) if you do not need all 48 SDK locales in an APK build; AAB language splits handle this automatically on Google Play.

Step 3: Add Packaging Exclusion

Add this to your app’s android block to avoid build conflicts:

android {
    packaging {
        resources {
            excludes += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
        }
    }
}

That’s it! Gradle will automatically resolve all transitive dependencies.

Permissions

The SDK requires the following permissions. These are declared in the SDK’s AndroidManifest.xml and will be merged automatically into your app’s manifest:

Permission	Source AAR	Description	Required
`INTERNET`	`didit-sdk-core`	Network access for API communication	Yes
`ACCESS_NETWORK_STATE`	`didit-sdk-core`	Detect network availability	Yes
`CAMERA`	`didit-sdk-core`	Document scanning and face verification	Yes
`NFC`	`didit-sdk-nfc`	Read NFC chips in passports/ID cards	Auto-merged from `didit-sdk-nfc` (transitive dependency of `me.didit:didit-sdk`)

Camera and NFC Features

The SDK declares android.hardware.camera and android.hardware.nfc as optional features (android:required="false"). This ensures your app can be installed on devices without a camera or NFC hardware — the SDK will gracefully handle missing hardware at runtime.

Quick Start

Step 1: Initialize the SDK

Initialize the SDK in your Application.onCreate():

import me.didit.sdk.DiditSdk

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        DiditSdk.initialize(this)
    }
}

Step 2: Start Verification and Handle Results

import me.didit.sdk.DiditSdk
import me.didit.sdk.DiditSdkState
import me.didit.sdk.VerificationResult

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

        // Observe SDK state to launch UI when ready
        lifecycleScope.launch {
            DiditSdk.state.collect { state ->
                when (state) {
                    is DiditSdkState.Ready -> DiditSdk.launchVerificationUI(this@MainActivity)
                    is DiditSdkState.Error -> Log.e("Didit", "Error: ${state.message}")
                    else -> { /* Loading, Idle, CreatingSession */ }
                }
            }
        }
    }

    private fun startVerification() {
        // Method 1: UniLink (no backend required)
        DiditSdk.startVerification(
            workflowId = "your-workflow-id",
            vendorData = "user-123"
        ) { result ->
            handleResult(result)
        }

        // Method 2: Backend Session (recommended for production)
        // DiditSdk.startVerification(
        //     token = "your-session-token"
        // ) { result ->
        //     handleResult(result)
        // }
    }

    private fun handleResult(result: VerificationResult) {
        when (result) {
            is VerificationResult.Completed -> {
                Log.d("Didit", "Session: ${result.session.sessionId}")
                Log.d("Didit", "Status: ${result.session.status}")
            }
            is VerificationResult.Cancelled -> {
                Log.d("Didit", "User cancelled")
            }
            is VerificationResult.Failed -> {
                Log.e("Didit", "Failed: ${result.error.message}")
            }
        }
    }
}

Integration Methods

The SDK supports two integration methods:

Method 1: UniLink (Simplest)

No backend required. The SDK creates the session directly using your workflow ID from the Didit Console. Limited to vendorData only.

DiditSdk.startVerification(
    workflowId = "your-workflow-id",
    vendorData = "user-123"
) { result ->
    handleResult(result)
}

Method 2: Backend Session (Recommended for Production)

Your backend creates the session via the Create Verification Session API (POST /v3/session/) with full parameter support (contact_details, expected_details, metadata, callback, etc.), then passes the session_token to the SDK.

// Your backend creates a session and returns the token
val sessionToken = yourBackend.createVerificationSession(userId = currentUser.id)

// Pass the token to the SDK
DiditSdk.startVerification(
    token = sessionToken
) { result ->
    handleResult(result)
}

This approach gives you full control over:

Associating sessions with your users (vendor_data)
Setting custom metadata
Configuring callbacks per session
Providing contact details and expected details for cross-validation

Configuration

Customize the SDK behavior:

import me.didit.sdk.Configuration
import me.didit.sdk.core.localization.SupportedLanguage

val configuration = Configuration(
    languageLocale = SupportedLanguage.SPANISH,  // Force Spanish language
    fontFamily = "my_custom_font",                // Custom font (must be in res/font/)
    loggingEnabled = true                         // Enable debug logging
)

DiditSdk.startVerification(
    token = "your-session-token",
    configuration = configuration
) { result ->
    handleResult(result)
}

Configuration Options

Property	Type	Default	Description
`languageLocale`	`SupportedLanguage?`	Device locale	Force a specific language
`fontFamily`	`String?`	System font	Custom font resource name (from `res/font/`)
`loggingEnabled`	`Boolean`	`false`	Enable SDK debug logging
`showCloseButton`	`Boolean`	`true`	Show close (X) button on verification step screens
`showExitConfirmation`	`Boolean`	`true`	Show confirmation dialog when user attempts to exit
`closeOnComplete`	`Boolean`	`false`	Auto-dismiss verification UI when complete (Web SDK equivalent: `closeModalOnComplete`)

Options showCloseButton, showExitConfirmation, and closeOnComplete match the Web SDK’s DiditSdkConfiguration. Mobile-specific options languageLocale and fontFamily exist because the mobile SDK renders the full verification UI natively (unlike the Web SDK which delegates to the hosted frontend inside an iframe).

Theming & Colors: Colors, backgrounds, and intro screen settings are configured through your White Label settings in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.

Language Support

The SDK supports 53 languages. If no language is specified, the SDK uses the device locale with English as fallback.

// Use device locale (default)
val config = Configuration()

// Force specific language
val config = Configuration(languageLocale = SupportedLanguage.FRENCH)

View All Supported Languages →

Advanced Options

For advanced session parameters (contact_details, expected_details, metadata, callback), use the Backend Session method. Your backend calls the Create Verification Session API with full parameters, then passes the session_token to the SDK.

Handling Results

The VerificationResult sealed class provides the outcome of the verification:

Result Cases

Case	Description
`Completed(session)`	Verification flow completed (check `session.status` for result)
`Cancelled(session)`	User cancelled the verification flow
`Failed(error, session)`	An error occurred during verification

SessionData Properties

Property	Type	Description
`sessionId`	`String`	Unique session identifier
`status`	`VerificationStatus`	`APPROVED`, `PENDING`, or `DECLINED`

Error Types

All errors are sealed subclasses of me.didit.sdk.VerificationError:

Error	Description
`SessionExpired`	The session has expired
`NetworkError`	Network connectivity issue
`CameraAccessDenied`	Camera permission not granted
`NotInitialized`	SDK not initialized — call `DiditSdk.initialize(context)` first
`ApiError`	Backend returned an error response
`RetryBlocked`	Verification cannot be retried (e.g., max attempts reached)
`Unknown(message)`	Other error with message

Complete Result Handling Example

DiditSdk.startVerification(token = "your-token") { result ->
    when (result) {
        is VerificationResult.Completed -> {
            when (result.session.status) {
                VerificationStatus.APPROVED -> {
                    Log.d("Didit", "Approved! Session: ${result.session.sessionId}")
                    // User is verified - grant access
                }
                VerificationStatus.PENDING -> {
                    Log.d("Didit", "Under review. Session: ${result.session.sessionId}")
                    // Show "verification in progress" UI
                }
                VerificationStatus.DECLINED -> {
                    Log.d("Didit", "Declined. Session: ${result.session.sessionId}")
                    // Handle declined verification
                }
            }
        }
        is VerificationResult.Cancelled -> {
            Log.d("Didit", "Cancelled: ${result.session?.sessionId ?: "unknown"}")
            // User chose to cancel - maybe show retry option
        }
        is VerificationResult.Failed -> {
            Log.e("Didit", "Error: ${result.error.message}")
            // Handle error - show retry or contact support
        }
    }
}

Observing SDK State

You can observe the SDK state for custom loading UI:

lifecycleScope.launch {
    DiditSdk.state.collect { state ->
        when (state) {
            is DiditSdkState.Idle -> {
                // Ready to start verification
            }
            is DiditSdkState.CreatingSession -> {
                // Show "Creating session..." progress
            }
            is DiditSdkState.Loading -> {
                // Show loading indicator
            }
            is DiditSdkState.Ready -> {
                // Verification UI is ready - launch it
                DiditSdk.launchVerificationUI(this@MainActivity)
            }
            is DiditSdkState.Error -> {
                // Show error message
                Log.e("Didit", "Error: ${state.message}")
            }
        }
    }
}

ProGuard / R8

The SDK includes its own consumer ProGuard rules. No additional configuration is needed. If you use R8 full mode, you may need to add this to your gradle.properties:

android.enableR8.fullMode=false

End-to-End Example (Backend Session → Android SDK → Result)

This pattern is the production-ready integration. Your backend creates the session, your Android app receives the session_token, and the SDK runs the flow.

1. Backend — create the session

// Node.js / Express example. Run on your server. NEVER ship DIDIT_API_KEY to the device.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/verification/start", async (req, res) => {
  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId, // your stable user id
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: `Didit ${response.status}` });
  }

  const { session_id, session_token } = await response.json();
  // Persist session_id <-> userId so you can match the webhook later.
  res.json({ session_id, session_token });
});

2. Android — exchange and start the SDK

import android.app.Activity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import me.didit.sdk.DiditSdk
import me.didit.sdk.VerificationResult
import me.didit.sdk.VerificationStatus
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import okhttp3.MediaType.Companion.toMediaType
import org.json.JSONObject

class VerificationFlow(private val activity: ComponentActivity) {
    private val http = OkHttpClient()
    private val json = "application/json".toMediaType()

    fun start(userId: String) {
        activity.lifecycleScope.launch {
            val token = withContext(Dispatchers.IO) {
                val body = JSONObject().put("userId", userId).toString().toRequestBody(json)
                val req = Request.Builder()
                    .url("https://your-backend.example.com/api/verification/start")
                    .post(body)
                    .build()
                http.newCall(req).execute().use { resp ->
                    JSONObject(resp.body!!.string()).getString("session_token")
                }
            }

            DiditSdk.startVerification(token = token) { result ->
                when (result) {
                    is VerificationResult.Completed -> when (result.session.status) {
                        VerificationStatus.APPROVED -> { /* optimistic UI; rely on webhook for source of truth */ }
                        VerificationStatus.PENDING  -> { /* show "under review" */ }
                        VerificationStatus.DECLINED -> { /* show retry/contact support */ }
                    }
                    is VerificationResult.Cancelled -> { /* user cancelled */ }
                    is VerificationResult.Failed    -> { /* show error: result.error.message */ }
                }
            }
        }
    }
}

3. Backend — receive the final decision via webhook

The SDK result is convenient for UI feedback, but the authoritative outcome arrives via webhook. See the Webhooks guide for HMAC verification.

app.post("/api/webhooks/didit", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the X-Signature header (see Webhooks docs)
  // 2. Parse the body
  const event = JSON.parse(req.body.toString());
  if (event.webhook_type === "status.updated") {
    // event.session_id, event.status ("Approved" | "Declined" | "In Review" | ...)
    // Look up the user by session_id and update their verification state.
  }
  res.sendStatus(200);
});

Complete Example

import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch
import me.didit.sdk.Configuration
import me.didit.sdk.DiditSdk
import me.didit.sdk.DiditSdkState
import me.didit.sdk.VerificationResult
import me.didit.sdk.VerificationStatus
import me.didit.sdk.core.localization.SupportedLanguage

class MainActivity : ComponentActivity() {

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

        // Observe SDK state
        lifecycleScope.launch {
            DiditSdk.state.collect { state ->
                when (state) {
                    is DiditSdkState.Ready -> DiditSdk.launchVerificationUI(this@MainActivity)
                    is DiditSdkState.Error -> Log.e("Didit", "Error: ${state.message}")
                    else -> { /* Idle, Loading, CreatingSession */ }
                }
            }
        }
    }

    fun startVerification() {
        val config = Configuration(
            languageLocale = SupportedLanguage.ENGLISH,
            loggingEnabled = true
        )

        // Method 1: UniLink (no backend required)
        DiditSdk.startVerification(
            workflowId = "your-workflow-id",
            vendorData = "user-123",
            configuration = config
        ) { result ->
            handleResult(result)
        }

        // Method 2: Backend Session (recommended for production)
        // DiditSdk.startVerification(
        //     token = "your-session-token",
        //     configuration = config
        // ) { result ->
        //     handleResult(result)
        // }
    }

    private fun handleResult(result: VerificationResult) {
        when (result) {
            is VerificationResult.Completed -> {
                when (result.session.status) {
                    VerificationStatus.APPROVED -> {
                        Log.d("Didit", "Approved! Session: ${result.session.sessionId}")
                    }
                    VerificationStatus.PENDING -> {
                        Log.d("Didit", "Under review")
                    }
                    VerificationStatus.DECLINED -> {
                        Log.d("Didit", "Declined")
                    }
                }
            }
            is VerificationResult.Cancelled -> {
                Log.d("Didit", "Cancelled: ${result.session?.sessionId ?: "unknown"}")
            }
            is VerificationResult.Failed -> {
                Log.e("Didit", "Error: ${result.error.message}")
            }
        }
    }
}

Guides

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Integrations

GitHub Repository

Native SDK: This is the recommended approach for Android apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.

Requirements

Installation

Step 1: Add the Repository

Step 2: Add the Dependency

SDK variants

Keeping the download small

Step 3: Add Packaging Exclusion

Permissions

Camera and NFC Features

Quick Start

Step 1: Initialize the SDK

Step 2: Start Verification and Handle Results

Integration Methods

Method 1: UniLink (Simplest)

Method 2: Backend Session (Recommended for Production)

Configuration

Configuration Options

Language Support

Advanced Options

Handling Results

Result Cases

SessionData Properties

Error Types

Complete Result Handling Example

Observing SDK State

ProGuard / R8

End-to-End Example (Backend Session → Android SDK → Result)

1. Backend — create the session

2. Android — exchange and start the SDK

3. Backend — receive the final decision via webhook

Complete Example

GitHub Repository

​Native SDK: This is the recommended approach for Android apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.

​Requirements

​Installation

​Step 1: Add the Repository

​Step 2: Add the Dependency

​SDK variants

​Keeping the download small

​Step 3: Add Packaging Exclusion

​Permissions

​Camera and NFC Features

​Quick Start

​Step 1: Initialize the SDK

​Step 2: Start Verification and Handle Results

​Integration Methods

​Method 1: UniLink (Simplest)

​Method 2: Backend Session (Recommended for Production)

​Configuration

​Configuration Options

​Language Support

​Advanced Options

​Handling Results

​Result Cases

​SessionData Properties

​Error Types

​Complete Result Handling Example

​Observing SDK State

​ProGuard / R8

​End-to-End Example (Backend Session → Android SDK → Result)

​1. Backend — create the session

​2. Android — exchange and start the SDK

​3. Backend — receive the final decision via webhook

​Complete Example

Native SDK: This is the recommended approach for Android apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.

Requirements

Installation

Step 1: Add the Repository

Step 2: Add the Dependency

SDK variants

Keeping the download small

Step 3: Add Packaging Exclusion

Permissions

Camera and NFC Features

Quick Start

Step 1: Initialize the SDK

Step 2: Start Verification and Handle Results

Integration Methods

Method 1: UniLink (Simplest)

Method 2: Backend Session (Recommended for Production)

Configuration

Configuration Options

Language Support

Advanced Options

Handling Results

Result Cases

SessionData Properties

Error Types

Complete Result Handling Example

Observing SDK State

ProGuard / R8

End-to-End Example (Backend Session → Android SDK → Result)

1. Backend — create the session

2. Android — exchange and start the SDK

3. Backend — receive the final decision via webhook

Complete Example