DataDome Android SDK 2.0

Android Kotlin SDK

Important
This version of the new SDK is still in beta. Do not integrate this experimental version into production.

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

The DataDome SDK has two major benefits:

1 - Network Tracking & captcha

Handles the 403 API response, generated by the DataDome server-side integration, to display the Captcha.

2 - Event Tracking

The SDK track user interactions inside the app, only when the app is in activity, and send it to DataDome API

Sample App

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

1- Installing SDK

minSdkVersion: 16

Gradle dependency

build.gradle in the root:

allprojects {
    repositories {
        mavenCentral()
    }
}

DataDome Kotlin SDK offers 2 integration options.

Manual integration

  • the Manual module that give us the ability to make API calls without extern libraries, we offer this light integration for an optimized application. You will need to call the SDK validateResponse method manually.

In your gradle add this dependency
Maven CentralMaven Central

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

OKHTTP integration

  • Okhttp inetgration is compatible with most of REST clients (OkHttpClient, Retrofit, Fast Android Networking Library) by setting up the interceptor

In your gradle for OkHttp, add the SDK dependency:
Maven CentralMaven Central

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

2- Initialize SDK

DataDome SDK instance with:

  • captchaListener: an SDKBaseListener implementation to decide what to do with captcha status
  • context: an activity instance
  • optional backBehavior: to customize the back-press behavior on captcha page between GO_BACKGROUND, BLOCKED, GO_BACK
    by default it is set to BLOCKED.
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

is an interface we implement if we need to specify an action related to the captcha status, for example we can show a toast to define the captcha status:

private val captchaListener = object : SDKBaseListener {
        override fun onCaptchaSucceed() {
            Toast.makeText(
                [email protected],
                "captcha solved successfully!",
                Toast.LENGTH_SHORT
            ).show()
        }

        override fun onCaptchaDismissed() {
            Toast.makeText(
                [email protected],
                "captcha has been dismissed",
                Toast.LENGTH_SHORT
            ).show()
        }

        override fun onCaptchaError() {
            Toast.makeText(
                [email protected],
                "an error has been detected when displaying captcha",
                Toast.LENGTH_SHORT
            ).show()
        }

        override fun onCaptchaLoaded() {
            Toast.makeText(
                [email protected],
                "Captcha did finish loading",
                Toast.LENGTH_SHORT
            ).show()
        }
    }

Manual Integration

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

OkHttp Integration

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

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

3- Client Key

You need to specify your DataDome client key in the AndroidManifest.xml as a meta-data under the application section, and we retrieve this value to track the device informations.

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

- Network tracking & Captcha

In case of a successful request, the SDK performs the callback as designed by the customer, otherwise, a 403 API response is returned by DataDome server-side and a captcha will be displayed.

- Event Tracking

The SDK tracks dynamic and static events. To ensure that actions has been triggered by a humain with a real Android device, DataDome collects general device informations and events and tracks view interactions and forward it to the DataDome API server to be analyzed.

Touch Screen 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");
}