SmartComply Android SDK

The SmartComply Android SDK delivers a fully self-contained identity verification flow for Android apps. Launch one Activity and the SDK handles session management, country and ID-type selection, document capture, identity verification, and liveness detection automatically.

Features

Single-Activity launch — start verification with one Intent and receive a typed result back
Two verification modes — document photo capture or ID number data entry, configured from your Dashboard
Guide-box document capture — frames the ID card precisely so images are always clean and correctly cropped
Liveness detection — a passive camera scan (blink plus natural head movement) runs automatically after identity verification, with no step-by-step prompts
Dynamic ID types — channels and fields are fetched live from your Dashboard configuration
Multi-country support — renders a country picker automatically when more than one country is configured
Dark and light mode — theme adapts to the system setting; override via the launch intent

Requirements

Android API 24 (Android 7.0) or later
Kotlin 2.1 or later — the SDK is compiled with the Kotlin 2.1 toolchain, so an older consumer compiler rejects it
Java 17 — the SDK targets JVM 17
Jetpack Compose enabled in your module

Installation

1 — Add Maven Central

In settings.gradle.kts (already present in most projects):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

2 — Add the dependency

In your app or feature module build.gradle.kts:

dependencies {
    implementation("io.github.386konsult:android-sdk:1.0.5")
}

Use 1.0.5 or later. 1.0.3 and 1.0.4 crash the host app: both read HTTP responses on the main thread, and 1.0.3 additionally crashes when the SDK is closed from a UI callback. Neither can be withdrawn from Maven Central, so pin deliberately.

3 — Enable Compose

android {
    buildFeatures {
        compose = true
    }
}

Credentials

Both values come from your Adhere Dashboard and both are permanent. Reuse the same pair for every verification.

Value	Where to find it	Notes
`apiKey`	Settings → API Keys	A 64-character alphanumeric string with no prefix
`clientId`	Settings → Integrations → SDK Setup, then the row menu → Integration → Client ID	The UUID of your SDK Config. It is issued by Adhere — do not generate one

clientId is not a per-attempt value. Generating your own UUID returns 404 SDK_CONFIG_NOT_FOUND on the very first call, because the server resolves it against an existing SDK Config record.

Permissions

The SDK declares these permissions automatically via manifest merge. You do not need to add them manually unless your project uses a custom manifest merge strategy:

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

SmartComplyActivity requests the CAMERA permission at runtime before it starts the flow, so if you launch through the Activity your app does not need to request it separately. If you embed SmartComplyFlowScreen directly, see Advanced: Custom Host Activity.

Quick Start

1 — Register the result launcher

In your Activity or Fragment:

import androidx.activity.result.contract.ActivityResultContracts
import com.smartcomply.sdk.ui.SmartComplyActivity

val verificationLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    val data = result.data ?: return@registerForActivityResult
    when (data.getStringExtra(SmartComplyActivity.RESULT_TYPE)) {
        SmartComplyActivity.TYPE_SUCCESS -> {
            val entryId    = data.getIntExtra(SmartComplyActivity.RESULT_ENTRY_ID, -1)
            val status     = data.getStringExtra(SmartComplyActivity.RESULT_STATUS)
            val idTypeName = data.getStringExtra(SmartComplyActivity.RESULT_ID_TYPE_NAME)
            // The user has finished their part of the flow. `status` is "processing";
            // the pass or fail verdict arrives later by webhook.
        }
        SmartComplyActivity.TYPE_CANCELLED -> {
            // user pressed back
        }
    }
}

2 — Launch verification

import com.smartcomply.sdk.client.Environment

val intent = SmartComplyActivity.buildIntent(
    from        = this,
    apiKey      = "YOUR_API_KEY",     // Settings → API Keys
    clientId    = "YOUR_CLIENT_ID",   // Settings → Integrations → SDK Setup
    environment = Environment.PRODUCTION
)
verificationLauncher.launch(intent)

Jetpack Compose

If you are launching from a composable, use rememberLauncherForActivityResult:

import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.ui.platform.LocalContext
import com.smartcomply.sdk.ui.SmartComplyActivity
import com.smartcomply.sdk.client.Environment

@Composable
fun StartVerificationButton() {
    val context = LocalContext.current

    val launcher = rememberLauncherForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->
        val data = result.data ?: return@rememberLauncherForActivityResult
        when (data.getStringExtra(SmartComplyActivity.RESULT_TYPE)) {
            SmartComplyActivity.TYPE_SUCCESS   -> { /* handle submission */ }
            SmartComplyActivity.TYPE_CANCELLED -> { /* user cancelled */ }
        }
    }

    Button(onClick = {
        val intent = SmartComplyActivity.buildIntent(
            from        = context,
            apiKey      = "YOUR_API_KEY",
            clientId    = "YOUR_CLIENT_ID",
            environment = Environment.PRODUCTION
        )
        launcher.launch(intent)
    }) {
        Text("Verify Identity")
    }
}

buildIntent Parameters

fun buildIntent(
    from:        Context,
    apiKey:      String,
    clientId:    String,
    darkTheme:   Boolean? = null,                    // null = follow system
    environment: Environment = Environment.PRODUCTION
): Intent

Parameter	Default	Description
`from`	—	The calling `Context`
`apiKey`	—	Your Adhere API key — find it in the Dashboard
`clientId`	—	Your SDK Config’s Client ID from the Dashboard. Permanent — reuse it for every verification
`darkTheme`	`null`	`true` forces dark mode, `false` forces light, `null` follows the device setting
`environment`	`PRODUCTION`	See Environments below

Environments

Value	Base URL
`Environment.PRODUCTION`	`https://adhere-api.smartcomply.com`
`Environment.SANDBOX`	`http://localhost:8000`

SANDBOX targets a server running on the handset itself, for local backend development. It is not a hosted test environment. Use PRODUCTION for all integration work.

SmartComplyActivity.buildIntent defaults to PRODUCTION, but the SDKConfig constructor used by the embedded flow defaults to SANDBOX. Set environment explicitly when you construct SDKConfig yourself.

Result Extras

Read from the Intent returned to your activity result callback.

Constant	Type	Present when
`RESULT_TYPE`	`String`	Always — `"success"` or `"cancelled"`
`RESULT_ENTRY_ID`	`Int`	`TYPE_SUCCESS` — the verification’s entry ID
`RESULT_STATUS`	`String`	`TYPE_SUCCESS` — `"processing"`
`RESULT_SUBMITTED_AT`	`String`	`TYPE_SUCCESS` — ISO 8601 timestamp
`RESULT_ID_TYPE_NAME`	`String`	`TYPE_SUCCESS` — e.g. `"National Identity Number (NIN)"`, `"Passport"`
`RESULT_ID_NUMBER`	`String`	`TYPE_SUCCESS` — the ID number the user entered, in data mode

The result is a submission receipt, not a verification verdict. RESULT_STATUS is "processing" when the user finishes: face matching, document OCR and the government database check all continue after the Activity returns. An entry’s status moves through pending, processing, and then passed, failed or expired. The final outcome arrives via webhook.

TYPE_CANCELLED is returned whenever the user leaves via the back button, including from the success screen. Treat RESULT_ENTRY_ID as the only reliable handle on a run, and reconcile the outcome from the webhook.

Verification Flow

The SDK steps through these screens automatically.

Step	Description
Loading	Session creation and brand config fetch
Welcome	Brand splash, country picker, and ID type selection
Camera Permission	Requests camera permission at runtime, in both modes, before the ID-input or capture step
Camera Permission Denied	”Camera Access Required” screen with Open Settings and Go Back
Document Capture (front)	Camera view with a guide box, a shutter, and Upload from gallery
Document Capture (back)	Shown for ID types whose name contains national, driver, resident or voter
ID Input	Form fields for data-mode verification (BVN, NIN, etc.)
Liveness	Passive camera scan — blink plus natural head movement, detected without naming the actions
Processing	Upload and backend submission in progress
Success	Submission complete — shows a summary card, then returns the result
Failure	Error screen with a retry button

Document images

Document photos are capped at 5 MB server-side, in JPG or PNG. Photos taken with the in-SDK camera are downscaled and compressed automatically. Images chosen with Upload from gallery are uploaded as-is, so a full-resolution phone photo can exceed the limit and fail with File too large. Maximum size is 5MB.

SDK Configuration

data class SDKConfig(
    val apiKey:             String,
    val clientId:           String,
    val environment:        Environment = Environment.SANDBOX,
    val requestTimeoutMs:   Long        = 30_000L,
    val uploadTimeoutMs:    Long        = 120_000L,
    val maxUploadRetries:   Int         = 3,
    val debug:              Boolean     = false
)

Parameter	Default	Description
`apiKey`	—	Your Adhere API key (required)
`clientId`	—	Your SDK Config’s Client ID (required)
`environment`	`SANDBOX`	Set this explicitly — see Environments
`requestTimeoutMs`	`30000`	Timeout in milliseconds for standard API calls, including identity verification
`uploadTimeoutMs`	`120000`	Timeout in milliseconds for image and video upload
`maxUploadRetries`	`3`	Automatic retry attempts when creating a liveness check. The final submit is not retried
`debug`	`false`	Prints verbose network logs to Logcat when `true`

Error Handling

SmartComplyActivity handles and displays all error states inside the flow — an invalid key, an expired session, or an exhausted upload retry all render the SDK’s own failure screen with a Try Again button. The Activity returns a result only when the user completes the flow or backs out.

Scenario	Cause	Resolution
Failure screen, invalid key	`apiKey` is wrong or the branch is not enabled for onboarding	Check your key in the Adhere Dashboard
Failure screen, no configuration found	`clientId` is not an active SDK Config	Copy the Client ID from Settings → Integrations → SDK Setup. Do not generate a UUID
Failure screen, session expired	Session tokens have a 30-minute TTL	Relaunch. A new session is created on each launch; your `clientId` never changes
`TYPE_CANCELLED`	User pressed back, from any screen	Reconcile against the webhook before assuming the user abandoned the flow

Advanced: Custom Host Activity

If you need to embed the verification flow directly inside your own ComponentActivity instead of launching a separate screen, you can use SmartComplyFlowScreen as a Compose composable:

import com.smartcomply.sdk.SmartComply
import com.smartcomply.sdk.client.SDKConfig
import com.smartcomply.sdk.client.Environment
import com.smartcomply.sdk.ui.SmartComplyFlowScreen

val sdk = SmartComply(
    SDKConfig(
        apiKey      = "YOUR_API_KEY",
        clientId    = "YOUR_CLIENT_ID",
        environment = Environment.PRODUCTION   // required: SDKConfig defaults to SANDBOX
    )
)

// In your composable:
SmartComplyFlowScreen(
    sdk        = sdk,
    darkTheme  = null,            // null = follow system setting
    onComplete = { result ->
        // result.entryId, result.status, result.submittedAt
    }
)

Your host Activity must be a ComponentActivity and must be in the foreground with an active window. Embedding SmartComplyFlowScreen inside a Dialog or bottom sheet will cause the camera to fail on some devices.

You do not need to request CAMERA yourself. From 1.0.2 the composable routes through its own permission screen in both verification modes, before the ID-input or document-capture step, and skips it silently once the permission is granted.On 1.0.1 and earlier data mode never asked, so if the permission had not already been granted the camera never opened: the liveness preview stayed black and the flow ended with Recording failed: Recording finalized with error code 4. If you are pinned to an older version, request CAMERA yourself before entering the flow, or launch through SmartComplyActivity, which always asked for both modes.

Dependencies

From 1.0.3 the SDK no longer depends on Ktor. It uses OkHttp directly, so your own Ktor version cannot conflict with ours.

On 1.0.2 and earlier, an app that uses Ktor 3 crashes on launch:

java.lang.NoClassDefFoundError: Failed resolution of:
Lio/ktor/client/plugins/contentnegotiation/ContentNegotiation;
    at com.smartcomply.sdk.SmartComply.<init>

Those versions were compiled against Ktor 2.3.12 and exported it, so Gradle resolved the conflict to your newer Ktor and linked our code against a version where the classes we call had been removed. There is no workaround on your side. Upgrade to 1.0.5.

ProGuard / R8

There is nothing to do. The SDK ships consumer ProGuard rules inside the AAR, so R8 applies them to your app automatically. They keep the generated kotlinx.serialization serializers and SmartComplyActivity; OkHttp ships its own rules in its jar.

On 1.0.1 and earlier, a minified build crashes on launch with a NoClassDefFoundError on a Ktor class. Those versions shipped no consumer rules. Upgrade to 1.0.5.

​SmartComply Android SDK

​Features

​Requirements

​Installation

​1 — Add Maven Central

​2 — Add the dependency

​3 — Enable Compose

​Credentials

​Permissions

​Quick Start

​1 — Register the result launcher

​2 — Launch verification

​Jetpack Compose

​buildIntent Parameters

​Environments

​Result Extras

​Verification Flow

​Document images

​SDK Configuration

​Error Handling

​Advanced: Custom Host Activity

​Dependencies

​ProGuard / R8

SmartComply Android SDK

Features

Requirements

Installation

1 — Add Maven Central

2 — Add the dependency

3 — Enable Compose

Credentials

Permissions

Quick Start

1 — Register the result launcher

2 — Launch verification

Jetpack Compose

buildIntent Parameters

Environments

Result Extras

Verification Flow

Document images

SDK Configuration

Error Handling

Advanced: Custom Host Activity

Dependencies

ProGuard / R8