> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Android

> Integrating Verisoul in Android Apps

*To run the SDK a Verisoul Project ID is required.* Schedule a call [here](https://meetings.hubspot.com/henry-legard) to get started.

## System Requirements

* Android 7.0 (API level 24) or higher
* Kotlin 1.5 or higher
* Gradle 7.0 or higher
* SDK Size: \~410 KB

## Installation

### Add Maven Repository

Add these lines to your `settings.gradle` file.

```kotlin theme={null}
dependencyResolutionManagement {
    repositories {
        ...
        maven { url = uri("https://us-central1-maven.pkg.dev/verisoul/android") }
    }
}
```

### Add Dependency

Add these lines to your `build.gradle` file.

#### For Groovy DSL

```kotlin theme={null}
dependencies {
  ...
  implementation "ai.verisoul:android:0.4.67"
}
```

#### For Kotlin DSL

```kotlin theme={null}
dependencies {
  ...
  implementation(libs.verisoul.android)
}
```

Add these lines to your `libs.versions.toml` file.

Under the `[versions]` add:

```kotlin theme={null}
verisoul = "0.4.67"
```

Under the `[libraries]` add:

```kotlin theme={null}
verisoul-android = { group = "ai.verisoul", name = "android", version.ref = "verisoul" }
```

## Usage

### Initialize the SDK

Call `init()` in your `Application` class's `onCreate()` method. Make sure to register this Application class in your `AndroidManifest.xml`.

**Application class:**

```kotlin theme={null}
import ai.verisoul.sdk.Verisoul
import ai.verisoul.sdk.VerisoulEnvironment

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        Verisoul.init(
            this,
            VerisoulEnvironment.Prod, // or VerisoulEnvironment.Sandbox
            "your-project-id"
        )
    }
}
```

**AndroidManifest.xml:**

```xml theme={null}
<manifest>
    <application
        android:name=".SampleApplication">
            ...
    </application>
</manifest>
```

The `init()` method initializes the Verisoul SDK with your project credentials. This method must be called once when your application starts.

**Parameters:**

* `context`: Your application context
* `environment`: The environment to use `VerisoulEnvironment.Prod` for production or `VerisoulEnvironment.Sandbox` for testing
* `projectId`: Your unique Verisoul project identifier

### Get Session ID

The `getSessionId()` method returns the current session identifier after the SDK has collected sufficient device data. This session ID is required to request a risk assessment from Verisoul's API.

**Important Notes:**

* Session IDs are short-lived and expire after 24 hours
* The session ID becomes available once minimum data collection is complete (typically within seconds)
* You should send this session ID to your backend, which can then call Verisoul's API to get a risk assessment

**Example:**

```kotlin theme={null}
Verisoul.getSessionId(
    callback = object : VerisoulSessionCallback {
        override fun onSuccess(sessionId: String) {
            // Send sessionId to your backend for risk assessment
        }

        override fun onFailure(exception: Exception) {
            // Handle exception
        }
    }
)
```

### Provide Touch Events

In order to gather touch events and compare them to device accelerometer sensor data, the app will need to provide touch events to Verisoul. The way to achieve this is to create `BaseActivity`, to override `dispatchTouchEvent` function and pass the data to Verisoul like shown below.

```kotlin theme={null}
open class BaseActivity : Activity() {

    override fun dispatchTouchEvent(event: MotionEvent?): Boolean {
        Verisoul.onTouchEvent(event)
        return super.dispatchTouchEvent(event)
    }

    // Other common BaseActivity code...
}
```

In the application, just use BaseActivity as an Activity base class.

```kotlin theme={null}
class MainActivity : BaseActivity() {

    // Other Activity code...
}
```

### Error Codes

The SDK throws `VerisoulException` with the following error codes:

| Error Code                 | Description                                                                                                                                                | Recommended Action                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| INVALID\_ENVIRONMENT       | The environment parameter passed to `Verisoul.init()` is invalid. Valid values are "dev", "sandbox", or "prod".                                            | Ensure the environment parameter is exactly "dev", "sandbox", or "prod" (case-sensitive, no whitespace).            |
| SESSION\_UNAVAILABLE       | A valid session ID could not be obtained. This typically occurs when Verisoul's servers are unreachable due to network blocking or a very slow connection. | Implement exponential backoff. Prompt user to check network or disable network blocker.                             |
| WEBVIEW\_UNAVAILABLE       | WebView is not available on the device. This can occur when WebView is disabled, missing, uninstalled, or corrupted on the device.                         | Prompt user to enable WebView in settings, update Android System WebView, or switch devices.                        |
| WEBVIEW\_RENDERER\_CRASHED | The WebView renderer process crashed, typically due to low memory or resource pressure.                                                                    | Retry the request (SDK will attempt recovery), encourage users to update Android System WebView, or switch devices. |

#### Exception Structure

All errors are thrown as `VerisoulException` with the following properties:

| Property | Type       | Description                                             |
| -------- | ---------- | ------------------------------------------------------- |
| code     | String     | One of the error codes above                            |
| message  | String     | Human-readable error description                        |
| cause    | Throwable? | The underlying exception that caused the error (if any) |

## Google Play Data Safety

For information on how to complete the Google Play Data Safety section when using the Verisoul SDK, please refer to our [Data Safety Instructions](https://support.verisoul.ai/articles/2377394661-verisoul-android-sdk-play-store-data-safety-instructions).

## Example

For a complete working example, see the [Android Sample App](/examples/android-sample-app).