> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/sdks/android-sdk.md).

# Android SDK

Integrate VOVE ID verification in a native Android application.

Use the SDK version your team has tested and approved.

## Install

Add JitPack to dependency resolution:

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven(url = "https://jitpack.io")
    }
}
```

Add the SDK:

```kotlin
dependencies {
    implementation("com.github.VOVE-ID:vove-id-android:1.5.0")
}
```

## Camera permission

Add the manifest permission:

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

Request it at runtime before starting and show a settings/recovery path if the user denies it permanently.

## Initialize and start

Initialize once, then start using a fresh token from your backend:

```kotlin
Vove.initialize(applicationContext, "ENVIRONMENT", "PUBLIC_KEY") { initialized ->
    if (!initialized) showInitializationError()
}

val options = Vove.StartOptions(
    showUI = true,
    maxAttemptsCallback = object : MaxAttemptsCallback {
        override fun onMaxAttemptsActionClicked() {
            showSupportOptions()
        }
    },
    exitAfterEachStep = false
)

Vove.start(this, sessionTokenFromBackend, { payload: VerificationPayload ->
    when (payload.result) {
        VerificationResult.SUCCESS -> showAwaitingServerConfirmation()
        VerificationResult.PENDING -> showPendingReview()
        VerificationResult.CANCELLED -> showVerificationCanceled()
        VerificationResult.MAX_ATTEMPTS_REACHED -> showSupportOptions()
        VerificationResult.IN_PROGRESS -> storeNextStep(payload.nextStep)
    }
}, options)
```

The SDK payload is a client journey signal. Reconcile it on your backend using a verified webhook and `GET /v2/users/{refId}`.

## Configuration

| Option                | Type     | Default | Description                                        |
| --------------------- | -------- | ------- | -------------------------------------------------- |
| `showUI`              | Boolean  | `true`  | Show the built-in welcome and summary screens.     |
| `maxAttemptsCallback` | callback | `null`  | Present support or another approved recovery path. |
| `exitAfterEachStep`   | Boolean  | `false` | Return control between verification steps.         |

Use the environment value supported by your installed SDK and keep the public key, session token, and environment aligned. VOVE ID environments are Sandbox and Production.

## Status values

Handle all values explicitly:

* `SUCCESS`
* `IN_PROGRESS`
* `PENDING`
* `CANCELLED`
* `MAX_ATTEMPTS_REACHED`

Unknown values should fail safely into pending review or an integration error. Do not convert them to success.

## Step-by-step journeys

```kotlin
val options = Vove.StartOptions(
    showUI = false,
    maxAttemptsCallback = null,
    exitAfterEachStep = true
)

Vove.start(this, sessionToken, { payload ->
    if (payload.result == VerificationResult.IN_PROGRESS) {
        routeToInterstepScreen(payload.nextStep)
    }
}, options)
```

The exact next step is flow-dependent. Resume with current server state and a valid token; do not assume a locally cached sequence is authoritative.

## Locale and vocal guidance

Use the SDK helpers rather than unchecked strings:

```kotlin
Vove.setLocale(this, VoveLocale.FR)
Vove.setEnableVocalGuidance(true)
```

Supported locales are:

| Value              | Language        |
| ------------------ | --------------- |
| `VoveLocale.EN`    | English         |
| `VoveLocale.FR`    | French          |
| `VoveLocale.DE`    | German          |
| `VoveLocale.AR`    | Arabic          |
| `VoveLocale.AR_MA` | Moroccan Arabic |

Test locale changes, right-to-left layouts, TalkBack, rotation, process recreation, and returning from background.

## Troubleshooting

| Symptom                            | Check                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| Gradle cannot resolve the artifact | Confirm JitPack is in dependency resolution and the coordinate uses `com.github.VOVE-ID`. |
| Camera is unavailable              | Confirm manifest and runtime permission and test on a real device.                        |
| Initialization fails               | Confirm public key and environment match.                                                 |
| Session token is rejected          | Fetch a fresh backend token and confirm it belongs to the same environment.               |
| Result disappears after rotation   | Store only UI state locally; reconcile authoritative state from the backend.              |

See [SDK compatibility](/docs/sdks/compatibility.md), [session creation](/docs/kyc-api/verification-session.md), and [production readiness](/docs/production-readiness.md).