# Android SDK

Integrate seamless ID verification and Know Your Customer (KYC) compliance into your Android applications with our streamlined VoveSDK. This guide outlines the steps to incorporate VoveSDK effectively into your Android projects.

## Installation

Incorporate VoveSDK into your project by adding it as a dependency in your app's `build.gradle` file, ensuring you have access to the required repository:

### Kotlin DSL (`build.gradle.kts`)

```groovy
repositories {
    maven { url 'https://jitpack.io' }
}

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

### Groovy DSL (`build.gradle`)

```groovy
repositories {
    maven { url 'https://jitpack.io' }
}

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

### Permissions

Add the necessary camera permission to your `AndroidManifest.xml`:

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

## Usage

### Initialize Vove SDK

To initialize the Vove SDK, use your public API key. This setup should ideally be done in your `Application` class as early as possible

```kotlin
Vove.initialize(context, "ENVIRONMENT", "PUBLIC_KEY") { isInitialized ->
    if (isInitialized) {
        println("success")
    } else {
        println("failure")
    }
}
```

### Starting a Verification Session

Start an ID verification session by invoking the SDK with a session token generated by your backend. Create a startVoveStartConfiguration and pass it, along with the session token, to the Vove.start function.

```kotlin
data class StartOptions(
    val showUI: Boolean = true,
    val maxAttemptsCallback: MaxAttemptsCallback? = null,
    val exitAfterEachStep: Boolean = false
)

fun start(
    context: Context,
    sessionToken: String,
    callback: (VerificationResult) -> Unit,
    options: StartOptions
)
```

### Configuration Options

* showUI (Boolean): Show or hide the SDK’s built‑in UI (e.g., welcome/summary).
* maxAttemptsCallback (MaxAttemptsCallback?): Optional callback invoked when the user reaches the maximum attempts.
* exitAfterEachStep (Boolean): When true, the SDK exits after each step so you can present your own UI and explicitly continue.

### Usage Examples

#### Basic Step‑by‑Step Verification (Kotlin)

```kotlin
val options = Vove.StartOptions(
    showUI = true,
    exitAfterEachStep = true,
    maxAttemptsCallback = object : MaxAttemptsCallback {
        override fun onMaxAttemptsActionClicked() {
            // Handle max attempts reached
        }
    }
)

Vove.start(context, sessionToken, { payload: VerificationPayload ->
    val nextStep = payload.nextStep?.name
    when (payload.result) {
        VerificationResult.SUCCESS -> {
            // Verification completed successfully
        }
        VerificationResult.IN_PROGRESS -> {
            // A verification step has completed
            // Next step: $nextStep
            // You can now start the next step or handle accordingly
        }
        VerificationResult.PENDING -> {
            // Verification is pending review
        }
        VerificationResult.CANCELLED -> {
            // User cancelled the verification
        }
        VerificationResult.MAX_ATTEMPTS_REACHED -> {
            // Maximum attempts reached
        }
    }
}, options)
```

#### Basic Step‑by‑Step Verification (Java)

```java
MaxAttemptsCallback maxAttemptsCallback = new MaxAttemptsCallback() {
    @Override
    public void onMaxAttemptsActionClicked() {
        // Handle max attempts reached
    }
};

Vove.StartOptions options = new Vove.StartOptions(
    true,  // showUI
    maxAttemptsCallback,
    true   // exitAfterEachStep
);

Vove.INSTANCE.start(context, sessionToken, (payload) -> {
    String nextStep = payload.getNextStep() != null ? payload.getNextStep().name();
    switch (payload.getResult()) {
        case SUCCESS:
            // Verification completed successfully,
            break;
        case IN_PROGRESS:
            // A verification step has been  completed
            // Next step: nextStep
            // You can now start the next step or handle accordingly
            break;
        case PENDING:
            // Verification is pending review
            break;
        case CANCELLED:
            // User cancelled the verification
            break;
        case MAX_ATTEMPTS_REACHED:
            // Maximum attempts reached
            break;
    }
}, options);
    @Override
    public void onMaxAttemptsActionClicked() {
        // Handle max attempts reached (e.g., open support, show help sheet)
    }
};
```

Start Options (New API)

* showUI (`Bool`) Show or hide the built-in Welcome and Summary screens.
* maxAttemptsActionCallback (\`MaxAttemptsCallback\`) Optional callback when the user reaches the maximum number of verification attempts. Use this to guide users to your support channel.
* exitAfterEachStep (`Bool`) If set to true, the SDK will exit after completing each step. This allows you to show your own UI between steps and control when to resume verification.

Handling Steps

When `exitAfterEachStep` is `true`, the `payload.nextStep` property will indicate which step should be presented next. You can use this to decide whether to:

* Continue the verification immediately.
* Show your own UI before resuming.
* Redirect the user elsewhere.

Example values for `nextStep` include:

* LIVENESS
* ID\_DOCUMENT
* ADDRESS\_PROOF
* CAR\_REGISTRATION\_DOCUMENT
* DONE

**Legacy Usage (Deprecated)**

Older versions started verification without StartOptions. This remains available for backward compatibility but will be removed in a future major release.

Kotlin:

```kotlin

Vove.start(context, VoveEnvironment.SANDBOX, "YOUR_SESSION_TOKEN") { verificationResult ->
    runOnUiThread {
        when (verificationResult) {
            VerificationResult.SUCCESS -> Toast.makeText(context, "Verification success", Toast.LENGTH_LONG).show()
            VerificationResult.PENDING -> Toast.makeText(context, "Verification pending", Toast.LENGTH_LONG).show()
            VerificationResult.CANCELLED -> Toast.makeText(context, "Verification canceled", Toast.LENGTH_LONG).show()
        }
    }
}
```

Java:

<pre class="language-java"><code class="lang-java">Vove.INSTANCE.start(context, VoveEnvironment.SANDBOX, "YOUR_SESSION_TOKEN", (result) -> {
    switch (verificationResult) {
        case SUCCESS:
        Toast.makeText(getApplicationContext(), "Verification success", Toast.LENGTH_LONG).show();
        break;
        case PENDING:
        Toast.makeText(getApplicationContext(), "Verification pending", Toast.LENGTH_LONG).show();
        break;
        case CANCELLED:
        Toast.makeText(getApplicationContext(), "Verification canceled", Toast.LENGTH_LONG).show();
        break;
<strong>    }
</strong>});
</code></pre>

⚠️ Deprecated: Please migrate to StartOptions + the updated start method for better control (exitAfterEachStep, maxAttemptsCallback) and forward compatibility.

### Setting the Application Locale

VoveSDK supports various locales to accommodate a diverse user base. You can programmatically set the locale to match the user's language and regional preferences, which enhances the user experience in multilingual applications or regions with specific language requirements.

To change the locale in VoveSDK, use the following method with the desired value from the `VoveLocale` enumeration:

```kotlin
 Vove.setLocale(context, VoveLocale.EN)
```

Here is the list of supported locales defined in the `VoveLocale` enumeration, which you can select to ensure the SDK’s text and user interface elements are presented in the chosen language:

* `VoveLocale.EN`: English
* `VoveLocale.FR`: French
* `VoveLocale.DE`: Deutch
* `VoveLocale.AR`: Arabic
* `VoveLocale.AR_MA`: Moroccan Arabic

### Enabling Vocal Guidance for 3D Liveness Verification

To enhance the user experience and accuracy during the 3D liveness verification process, VoveSDK on Android offers an optional vocal guidance feature. This feature provides audio instructions to guide users through the verification process, helping them position themselves correctly in front of the camera.

```kotlin
Vove.setEnableVocalGuidance(true)
```

When enabled, the SDK provides voice instructions during the 3D liveness verification step, aiding users in performing the necessary actions correctly and efficiently.

### Hiding the Welcome and Summary Pages

You can control whether the SDK displays its built-in welcome and summary screens using the optional showUI parameter. By default, showUI is set to true, which enables these screens. To hide them and fully manage the user experience within your app, set showUI to false.

**Example Usage:**

```swift
data class StartOptions(
    val showUI: Boolean = false,
)

fun start(
    context: Context,
    sessionToken: String,
    callback: (VerificationResult) -> Unit,
    options: StartOptions
)
```

## Support

By following the steps outlined in this guide, you can effectively integrate the VoveSDK into your Android applications, ensuring efficient and secure ID verification and KYC compliance. For further assistance or questions, please contact our support team.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voveid.com/docs/sdks/android-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.