Android SDK - Didit Documentation

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	21+ (Android 5.0 Lollipop). 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 21–23 devices the SDK falls back to manual capture with a timed shutter button. All other features work across the full API 21+ 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:3.5.8")
}

Or if using build.gradle (Groovy):

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

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

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

​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

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