This guide describes how to integrate the DataDome Kotlin SDK in your Android application.

Features

Request interception & challenge display: the SDK will handle requests blocked by DataDome and display challenges returned by the protection.
Event tracking: the SDK will sample metadata about user interactions from the application and send them to the DataDome API to improve the detection.

Sample application

Below is a sample app demonstrating the implementation of DataDomeSDK in a basic Kotlin application.

github.com

GitHub - DataDome/AndroidSDK-Example

Installing the SDK

Minimum SDK version

minSdkVersion: 16

Gradle dependency

In the build.gradle file at the project's root:

allprojects {
    repositories {
        mavenCentral()
    }
}

Integration modes

OkHttp integration

The OkHttp integration is compatible with most HTTP clients (OkHttpClient, Retrofit, Fast Android Networking Library) by setting up a network interceptor.

In your gradle configuration for OkHttp, you must add this dependency:

dependencies {
    implementation 'co.datadome.sdk:okhttp:2.0.0'
}

Manual integration

The manual integration mode allows API calls to be made without external libraries. You will need to call the validateResponse method manually.

In your gradle configuration, you must add this dependency:

dependencies {
    implementation 'co.datadome.sdk:sdk:2.0.0'
}

Initializing the SDK

The SDK needs to be instantiated with:

captchaListener: an implementation of SDKBaseListener to be notified with the status of a challenge
context: an activity instance
backBehavior (optional): to customize the back-press behavior on a challenge page between GO_BACKGROUND, BLOCKED (default), and GO_BACK.

private lateinit var dataDomeSDK: SDKBase

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    dataDomeSDK = SDKBase
        .Builder()
        .listener(captchaListener)
        .context(this)
        .backBehavior(BackBehavior.GO_BACK)
        .build()
 }

CAPTCHA listener

This is an interface that we implement if we need to specify an action related to the status of a challenge page. For example, we can show a toast with this information:

private val captchaListener = object : SDKBaseListener {
    override fun onCaptchaSucceed() {
        Toast.makeText(
            this@MainActivity,
            "captcha solved successfully!",
            Toast.LENGTH_SHORT
        ).show()
    }

    override fun onCaptchaDismissed() {
        Toast.makeText(
            this@MainActivity,
            "captcha has been dismissed",
            Toast.LENGTH_SHORT
        ).show()
    }

    override fun onCaptchaError() {
        Toast.makeText(
            this@MainActivity,
            "an error has been detected when displaying captcha",
            Toast.LENGTH_SHORT
        ).show()
    }

    override fun onCaptchaLoaded() {
        Toast.makeText(
            this@MainActivity,
            "Captcha did finish loading",
            Toast.LENGTH_SHORT
        ).show()
    }
}

OkHttp integration

//Setup the interceptor
val interceptor = DataDomeOkHttp3Interceptor(dataDomeSDK)

//Setup the client
val client = okhttp3.OkHttpClient()
    .newBuilder()
    .addInterceptor(interceptor)
    .build()

Manual integration

dataDomeSDK.validateResponse(
    Response(responseCode,data,headers),
    Request(url,headers),
    retryCallback = {
        // retry failed requests
    },
    successCallback = {
        // actions when request pass the captcha
    }
)

Client-side API key

The client-side API key from your DataDome account must be added to AndroidManifest.xml as a meta-data under the application section.

<meta-data
  android:name="co.datadome.sdk.client.key"
  android:value="xxxxxxxxxxxxxxxxxxxxxx"/>

Request interception & challenge display

In case of a successful request, the SDK performs the callback as implemented by the application. If a request is blocked with a 403 response by DataDome, a challenge page with a CAPTCHA will be displayed.

Event tracking

The SDK tracks static information and dynamic events. To ensure that actions are performed by a human with a real Android device, the SDK collects information on the device itself and events on interactions, and forwards it to the DataDome API.

Touch event tracking

/**
 * This method is called when activity view has been touched
 * @param view The view to log gestures on
 */
fun logGesture(view: View) {
    view.setOnTouchListener(EventTracker.shared.gestureListener())
}

Custom event tracking

/**
 * An enum representing supported event types
 */
enum class EventType(private val value: String) {
    /** Logged when an app/activity context is unexpectedly found null */
    NULL_CONTEXT("null activity reference"),

    /** Logged when a response is being validated */
    RESPONSE_VALIDATION("response validation"),

    /** Logged when a captcha is passed successfully */
    CAPTCHA_SUCCESS("captcha success"),

    /** Logged when a touch down gesture is detected */
    TOUCH_DOWN("touch down"),

    /** Logged when a touch up gesture is detected */
    TOUCH_UP("touch up"),

    /** Logged when a touch move gesture is detected */
    TOUCH_MOVE("touch move");
}