> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vlenseg.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vlenseg.com/_mcp/server.

# Android SDK

The VLens Android SDK embeds the full identity verification experience — national ID scanning, liveness detection, and face matching — directly into your Android app with a single method call.

#### [Maven Central](https://central.sonatype.com/artifact/io.github.vlens2021/vlens-sdk)

vlens-sdk · v1.0.2

#### Min SDK

API 26 (Android 8.0)+

#### Language

Kotlin 1.9.10+, Target SDK 35

---

## Installation

### Method 1: Maven Central (Recommended)

Add the dependency to your app's `build.gradle`:

#### Kotlin DSL

```kotlin
dependencies {
    implementation("io.github.vlens2021:vlens-sdk:1.0.2")
}
```

#### Groovy DSL

```groovy
dependencies {
    implementation 'io.github.vlens2021:vlens-sdk:1.0.2'
}
```

#### Maven

```xml
<dependency>
    <groupId>io.github.vlens2021</groupId>
    <artifactId>vlens-sdk</artifactId>
    <version>1.0.2</version>
</dependency>
```

All transitive dependencies (CameraX, ML Kit, Retrofit, etc.) are automatically included. You do not need to add them manually.

### Method 2: Manual AAR

If you prefer to use the AAR file directly:

1. Copy the `VLens-release.aar` file into your project's `app/libs/` directory.
2. Add the file and its required dependencies to your `build.gradle`:

#### Kotlin DSL

```kotlin
dependencies {
    implementation(files("libs/VLens-release.aar"))

    implementation("com.github.mrmike:ok2curl:0.8.0")
    implementation("androidx.fragment:fragment-ktx:1.8.5")
    implementation("androidx.camera:camera-core:1.4.2")
    implementation("androidx.camera:camera-lifecycle:1.4.2")
    implementation("androidx.camera:camera-camera2:1.4.2")
    implementation("androidx.camera:camera-view:1.4.2")
    implementation("com.google.mlkit:face-detection:16.1.7")
    implementation("com.google.mlkit:text-recognition:16.0.1")
    implementation("com.squareup.okhttp3:logging-interceptor:4.11.0")
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("pl.droidsonroids.gif:android-gif-drawable:1.2.29")
    implementation("com.google.zxing:core:3.3.0")
}
```

#### Groovy DSL

```groovy
dependencies {
    implementation files('libs/VLens-release.aar')

    implementation 'com.github.mrmike:ok2curl:0.8.0'
    implementation 'androidx.fragment:fragment-ktx:1.8.5'
    implementation 'androidx.camera:camera-core:1.4.2'
    implementation 'androidx.camera:camera-lifecycle:1.4.2'
    implementation 'androidx.camera:camera-camera2:1.4.2'
    implementation 'androidx.camera:camera-view:1.4.2'
    implementation 'com.google.mlkit:face-detection:16.1.7'
    implementation 'com.google.mlkit:text-recognition:16.0.1'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.11.0'
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.29'
    implementation 'com.google.zxing:core:3.3.0'
}
```

---

## Quick start

Import and call `VLensManager().init()` from your Activity or Fragment:

```kotlin
import com.silverkey.vlens.VLensManager

VLensManager().init(
    context = this@MainActivity,
    sdkConfig = VLensManager.SdkConfig(
        transactionId = transactionId,
        env = VLensManager.EnvironmentConfig(
            apiBaseUrl = "https://api.vlenseg.com",
            accessToken = accessToken,
            refreshToken = refreshToken,
            apiKey = "YOUR_API_KEY",
            tenancyName = "YOUR_TENANT"
        ),
        getExtractedData = true,
        defaultLocale = "en"
    ),
    onSuccess = { extractedData ->
        val name = extractedData?.idFrontData?.name
        Toast.makeText(this, "Verified: $name", Toast.LENGTH_SHORT).show()
    },
    onFaild = { errorCode, errorMsg ->
        Toast.makeText(this, "Error $errorCode: $errorMsg", Toast.LENGTH_SHORT).show()
    }
)
```

---

## Configuration

### `EnvironmentConfig`

| Parameter      | Type     | Description                                        |
| -------------- | -------- | -------------------------------------------------- |
| `apiBaseUrl`   | `String` | Vlens API base URL — use `https://api.vlenseg.com` |
| `accessToken`  | `String` | User JWT from registration or login                |
| `refreshToken` | `String` | Token used to refresh the access token             |
| `apiKey`       | `String` | Your tenant API key                                |
| `tenancyName`  | `String` | Your tenant name                                   |

### `SdkConfig` — all parameters

| Parameter               | Type                | Default | Description                                  |
| ----------------------- | ------------------- | ------- | -------------------------------------------- |
| `transactionId`         | `String`            | —       | Unique identifier for the transaction        |
| `env`                   | `EnvironmentConfig` | —       | API credentials and endpoint                 |
| `isLivenessOnly`        | `Boolean`           | `false` | Skip ID scanning — liveness check only       |
| `isNationalIdOnly`      | `Boolean`           | `false` | Skip liveness — ID scan only                 |
| `getExtractedData`      | `Boolean`           | `false` | Return OCR-extracted fields in `onSuccess`   |
| `defaultLocale`         | `String`            | `"en"`  | UI language — `"en"` or `"ar"`               |
| `colors`                | `Colors`            | —       | Light and dark theme colours                 |
| `detectionRetryCounter` | `Int`               | `5`     | Liveness retries allowed before failure      |
| `disableAutoCapture`    | `Boolean`           | `false` | Require manual capture for ID front and back |
| `errorMessages`         | `List<ApiError>`    | `[]`    | Override default error messages              |

### `Colors` and `ColorConfig`

```kotlin
colors = VLensManager.Colors(
    light = VLensManager.ColorConfig(
        accent = "#4E5A78",
        primary = "#397374",
        secondary = "#FF4081",
        background = "#FEFEFE",
        dark = "#000000",
        light = "#FFFFFF"
    ),
    dark = VLensManager.ColorConfig(
        accent = "#FFC107",
        primary = "#2196F3",
        secondary = "#FF4081",
        background = "#000000",
        dark = "#FFFFFF",
        light = "#000000"
    )
)
```

---

## Verification modes

#### Full verification (default)

Runs the complete flow: ID front → ID back → liveness.

```kotlin
VLensManager().init(
    context = this,
    sdkConfig = VLensManager.SdkConfig(
        transactionId = transactionId,
        isLivenessOnly = false,
        isNationalIdOnly = false,
        getExtractedData = true,
        env = VLensManager.EnvironmentConfig(
            apiBaseUrl = "https://api.vlenseg.com",
            accessToken = accessToken,
            refreshToken = refreshToken,
            apiKey = "YOUR_API_KEY",
            tenancyName = "YOUR_TENANT"
        ),
        defaultLocale = "ar"
    ),
    onSuccess = { data -> /* handle success */ },
    onFaild = { code, msg -> /* handle failure */ }
)
```

#### Liveness only

```kotlin
VLensManager().init(
    context = this,
    sdkConfig = VLensManager.SdkConfig(
        transactionId = transactionId,
        isLivenessOnly = true,
        env = VLensManager.EnvironmentConfig(
            apiBaseUrl = "https://api.vlenseg.com",
            accessToken = accessToken,
            refreshToken = refreshToken,
            apiKey = "YOUR_API_KEY",
            tenancyName = "YOUR_TENANT"
        )
    ),
    onSuccess = { _ -> /* liveness passed */ },
    onFaild = { code, msg -> /* handle failure */ }
)
```

#### ID scan only

```kotlin
VLensManager().init(
    context = this,
    sdkConfig = VLensManager.SdkConfig(
        transactionId = transactionId,
        isNationalIdOnly = true,
        getExtractedData = true,
        env = VLensManager.EnvironmentConfig(
            apiBaseUrl = "https://api.vlenseg.com",
            accessToken = accessToken,
            refreshToken = refreshToken,
            apiKey = "YOUR_API_KEY",
            tenancyName = "YOUR_TENANT"
        )
    ),
    onSuccess = { data ->
        val name = data?.idFrontData?.name
        val idNumber = data?.idFrontData?.idNumber
    },
    onFaild = { code, msg -> /* handle failure */ }
)
```

---

## Handling results

### `onSuccess` — `ExtractData`

When `getExtractedData = true`, the `onSuccess` callback receives an `ExtractData` object:

```kotlin
onSuccess = { extractedData ->
    // Verification status
    val verified = extractedData?.isDigitalIdentityVerified

    // User profile
    val user = extractedData?.user
    println(user?.fullName)
    println(user?.phoneNumber)
    println(user?.emailAddress)
    println(user?.idNumber)

    // ID front
    val front = extractedData?.idFrontData
    println(front?.name)           // Arabic full name
    println(front?.nameEnglish)    // Transliterated name
    println(front?.idNumber)
    println(front?.dateOfBirth)
    println(front?.gender)
    println(front?.govern)

    // ID back
    val back = extractedData?.idBackData
    println(back?.maritalStatus)
    println(back?.job)
    println(back?.religion)
    println(back?.idExpiry)
    println(back?.releaseDate)
}
```

### `ExtractData` — full field reference

**`user`**

| Field          | Type     |
| -------------- | -------- |
| `id`           | `Int`    |
| `name`         | `String` |
| `surname`      | `String` |
| `fullName`     | `String` |
| `userName`     | `String` |
| `emailAddress` | `String` |
| `phoneNumber`  | `String` |
| `idNumber`     | `String` |
| `address`      | `String` |

**`idFrontData`**

| Field                                   | Type                           |
| --------------------------------------- | ------------------------------ |
| `name`                                  | `String` — Arabic full name    |
| `nameEnglish`                           | `String` — Transliterated name |
| `firstName` / `lastName`                | `String`                       |
| `firstNameEnglish` / `lastNamesEnglish` | `String`                       |
| `idNumber`                              | `String`                       |
| `idKey`                                 | `String`                       |
| `dateOfBirth`                           | `String`                       |
| `gender`                                | `String`                       |
| `govern` / `governEnglish`              | `String`                       |
| `address` / `addressEnglish`            | `String`                       |
| `city` / `district`                     | `String`                       |
| `transactionId` / `requestId`           | `String`                       |

**`idBackData`**

| Field                                    | Type     |
| ---------------------------------------- | -------- |
| `maritalStatus` / `maritalStatusEnglish` | `String` |
| `job` / `jobEnglish`                     | `String` |
| `jobTitle` / `jobTitleEnglish`           | `String` |
| `religion` / `religionEnglish`           | `String` |
| `husbandName` / `husbandNameEnglish`     | `String` |
| `gender` / `genderEnglish`               | `String` |
| `releaseDate`                            | `String` |
| `idExpiry`                               | `String` |
| `idNumber`                               | `String` |
| `transactionId` / `requestId`            | `String` |

### `onFaild`

```kotlin
onFaild = { errorCode, errorMsg ->
    // Log or display the error
    Log.e("VLens", "Error $errorCode: $errorMsg")
}
```

### Custom error messages

```kotlin
errorMessages = listOf(
    VLensManager.ApiError(
        errorCode = 101,
        errorMessageEn = "Network error. Please check your connection.",
        errorMessageAr = "خطأ في الشبكة. يرجى التحقق من الاتصال."
    )
)
```

---

## Security notes

* Store API credentials (access token, refresh token, API key) securely — never hardcode them in production builds.
* Use Android Keystore or a secrets management solution for runtime credential storage.

## Support

For issues or inquiries, contact [support@vlenseg.com](mailto:support@vlenseg.com) with your tenant name, the error code and message, and the SDK version.