Android SDK

This guide will help you integrate Verisoul’s Android SDK into your native Android apps, configure it, retrieve a session ID, and handle errors.

See Android Example App for a comprehensive example app

In This Guide, You Will Learn How To:

• Include the SDK: Add Verisoul’s Android SDK to your project via Maven
• Configure the SDK: Initialize the SDK with your environment and project ID
• Retrieve a Session ID: Obtain a unique session identifier to validate user authenticity.
• Provide Touch Events: Capture additional behavioral telemetry to bolster fraud detection.
• Handle Errors: Implement basic error handling for robust integration.

Prerequisites

• Android Studio: Version 2022.1 (Electric Eel) or higher is recommended.
• Android Min SDK: 24 or higher (recommended).
• Project ID: A valid Verisoul project identifier is required to initialize the SDK.

Including the SDK in Your App

1. Add Repository

Add these lines to your settings.gradle file.

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

2. Add Dependency

Add these lines to your build.gradle file.

For Groovy DSL

dependencies {
  ...
  implementation "ai.verisoul:android:1.0.6"
}

For Kotlin DSL

dependencies {
  ...
  implementation(libs.verisoul.android)
}

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

Under the [versions] add:

verisoul = "1.0.6"

Under the [libraries] add:

verisoul-android = { group = "ai.verisoul", name = "android", version.ref = "verisoul" }

Configuring the SDK

Initialization should be called in overridden onCreate() function from Application class that should be defined in the AndroidManifest.xml file. For example:

Application class

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        Verisoul.init(
            this,
            VerisoulEnvironment.Prod, // or Sandbox
            "<VERISOUL_PROJECT_ID>"
        )
    }
}

AndroidManifest.xml

<manifest>
    <application
        android:name=".SampleApplication">
            ...
    </application>
</manifest>

When this is called Verisoul library will be initialized, initial data together with session ID will be gathered and uploaded to Verisoul backend.

Retrieving a Session ID

Once the minimum amount of data is gathered the session ID becomes available.
The session ID is needed in order to request a risk assessment from Verisoul's API. Note that session IDs are short lived and will expire after 24 hours. The application can obtain session ID by providing the callback as shown below:

Verisoul.getSessionId(
    callback = object : VerisoulSessionCallback {
        override fun onSuccess(sessionId: String) {
            // Upload session ID to backend
        }

        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.

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.

class MainActivity : BaseActivity() {

    // Other Activity code...
}

Error Handling

If the session retrieval process fails (for example, if the device is offline), Verisoul throws an error.

We recommend not letting a user proceed past a "critical event" in your application without having a session_id to balance security and user experience. Typical "critical events" include signup, a monetary transaction or any point in your application flow where a fraudulent user can extract value.