Android SDK

Latest Version: 1.5.0

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)

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

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

Groovy DSL (build.gradle)

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:

<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

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.

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)

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)

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:

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:

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

⚠️ 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:

 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.

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:

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.