Android SDK

The DataDome Android SDK is a lightweight library designed to integrate DataDome protection into Android apps.Its key features include:

Analyzing HTTP requests and displaying challenge page to users when suspicious activity is detected.
Retrying blocked request once the challenge is resolved.
Collecting behavioral signals to enhance our Machine Learning models to improve detection. Refer to Google Play data security for further details.

Prerequisites

Make sure your project meets these requirements to ensure proper integration:

Minimum API level (minSdkVersion): 16

Minimum API level (minSdkVersion): 19
Minimum Kotlin version: 1.9.0

Permissions

Starting from version 1.13.9, the SDK uses the android.permission.ACCESS_NETWORK_STATE permission.

This is a normal permission that is automatically granted at application install and does not require any user approval at runtime.

Install the SDK

Add Maven Central Repository:

In your build.gradlefile:

allprojects {
    repositories {
        mavenCentral()
    }
}

Add SDK dependency:

In your modules's build.gradlefile:

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

We recommend you to use the latest version.

Configure the SDK

Common configuration

Initialize the SDK with an application context:

DataDomeSDK.Builder dataDomeSDK = DataDomeSDK.with(application, 
                                           "Client_Side_Key", 
                                           BuildConfig.VERSION_NAME,  
                                           new DataDomeConfiguration(new URL("https://your_domain.com"));

Note: Starting from version 1.15.0, when initializing the SDK, you must provide the base URL of your app’s API domain using the DataDomeConfiguration parameter. This should be the fully qualified domain (e.g., https://your_domain.com) that your app communicates with.

Then set optional parameters to further customize the SDK:

DataDomeSDK.Builder dataDomeSDK = DataDomeSDK
                                  .with(getApplication(),
                                        "Client_Side_Key",
                                        BuildConfig.VERSION_NAME,
                                        new DataDomeConfiguration(new URL("https://your_domain.com")))
                                  .backBehaviour(BackBehaviour.GO_BACKGROUND)
                                  .activateDatadomeLogger(true)
                                  .setResponsePageLanguage("en");

The table below outlines all parameters you can configure with the SDK:

Parameter	Description	Type	Default Value
`.listener(DataDomeSDKListener listener)`	Optional. Sets a listener to handle the status of DataDome response page	`DataDomeSDKListener`	`null`
`.agent(String userAgent)`	Deprecated. Sets a custom User Agent for event tracking	`String`	Default User Agent
`.bypassAcceptHeader(Boolean bypassAcceptHeader)`	Deprecated. The SDK now supports HTML response challenges, in addition to the originally supported JSON responses. Bypasses the DataDome `Accept` header Use this option only for SFCC module integration or when a custom Accept header is needed in versions prior to v1.14.0	`Boolean`	`false`
`.backBehaviour(BackBehaviour behaviour)`	Optional. Defines the behavior of the back button on the response page Options are: `GO_BACKGROUND`, `BLOCKED`, `GO_BACK`.	`BackBehaviour`	`GO_BACKGROUND`
`.activateDatadomeLogger(Boolean activate)`	Optional. Enables a verbose logger for more details	`Boolean`	`false`
`.setResponsePageLanguage(String language)`	Optional. Sets the language of DataDome response pages	`String` Language code (as define in the RFC 7231 section 5.3.5 )	Application language

Advanced configuration

Integrate with CookieJar

CookieJar manages HTTP cookies with custom policies. It should be synchronized with DataDome cookie, otherwise it can lead to a potential challenge infinite loop.
Follow these steps for proper integration:

Use DataDomeCookieJar

// Integrating DataDomeCookieJar with your CookieJar instance as parameter
builder.cookieJar(dataDomeInterceptor.getDataDomeCookieJar(cookieJar))

Alternatively, set the DataDome cookie manually:

@NonNull
@Override
public List<Cookie> loadForRequest(@NonNull HttpUrl url) {
  List<Cookie> cacheCookies;
  cacheCookies = cookieStore.get(url.toString());
  String datadomeCookie = dataDomeSdkInstance.getCookieWithAttributes();
  if(datadomeCookie !=  null && !datadomeCookie.isEmpty()) {
    cacheCookies.add(Cookie.parse(url, datadomeCookie)));
  }
  return cacheCookies != null ? cacheCookies : new ArrayList<>();
}

Integrate with Third-Party Libraries

For third-party libraries like PersistentCookieJar, use:

// PersistentCookieJar instance
val cookieJar: ClearableCookieJar =
            PersistentCookieJar(SetCookieCache(), SharedPrefsCookiePersistor(context))
// Integrating DataDomeCookieJar with the PersistentCookieJar instance as parameter 
builder.cookieJar(dataDomeInterceptor.getDataDomeCookieJar(cookieJar))

Usage

Enable protection

To protect your application, choose one or more integrations based on your networking layer:

OkHttp interceptor (The default and recommended integration, for OkHttp users)
Manual integration

We strongly recommend using OkHttp integration whenever possible.

Share DataDome cookie between native and Webview

If your application uses Webview to display web pages protected by DataDome, you need to share DataDome cookie between the HTTP client instances of mobile app and the Webview. This ensures that users won't face multiple challenges when navigating between the app and web-based content.

There are 2 ways to achieve this. The recommended approach is to use the DataDomeWebview provided by the SDK. However, if some constraints prevent you from using it, you can still do the cookie sharing manually.

Use `DataDomeWebview` (Recommended)

Implementation

Replace the standard Webview with DataDomeWebView in your XML layout:

<co.datadome.sdk.DataDomeWebView
    android:id="@+id/datadomeWebView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Or instantiate it programmatically:

DataDomeWebView dataDomeWebView = new DataDomeWebView(context);

Then use it like a standard webview:

webview.loadUrl(url);

Warnings and limitations

DataDomeWebview provides automatic cookie sharing between WebView and native SDK using the WebView lifecycle. That means DataDome cookie is synchronized when the WebView finishes loading, or when the page is paused, closed or destroyed.

Not covered cases:

Cookie has been updated via non-trackable events (e.g. XHR, JS HTTP requests) and no UI state changes has been detected.
The WebView is within a legacy fragment on Android versions < Android O, and no back stack change occurs.

In cases where automatic update does not occur, share DataDome cookie manually by following the steps in section Share DataDome Cookie from WebView to SDK below once you are aware that cookie has been updated.

Share cookie manually

Share DataDome Cookie from SDK to WebView

// Retrieve the latest DataDome cookie from the SDK
String cookie = dataDomeSdk.getCookieWithAttributes();

// Set the DataDome cookie in the WebView's CookieManager
CookieManager.getInstance().setCookie(url, cookie);

// Load the desired URL in the WebView
webview.loadUrl(url);

The getCookieWithAttributes API returns the last stored DataDome cookie with its attributes. It is important to set this cookie to the webview CookieManager, as CookieManager expects cookies to include attributes. This ensures proper behavior and prevents potential issues.

Share DataDome Cookie from WebView to SDK

// Retrieve all cookies from the WebView
String cookies = CookieManager.getInstance().getCookie(url);

// Filter out the DataDome cookie if there are multiple cookies
String datadomeCookie = filterDatadomeCookie(cookies);

// Store the DataDome cookie in the SDK
dataDomeSdk.setCookie(datadomeCookie);

filterDatadomeCookieextracts the DataDome cookie from a set of multiples cookies. It can be implemented as below:

private String filterDatadomeCookie(String cookie) {
  String cookieName = "datadome=";
  String[] cookieSplit = cookie.split(cookieName);
  if (cookieSplit.length > 1) {
    if (cookieSplit[1].contains(";")) {
      return cookieName+cookieSplit[1].split(";")[0];
    }
    return cookieName+cookieSplit[1];
  }
  return "";
}

Mobile signals collection

DataDome collects minimal, non-personal data from users to improve the detection. All data is stored using high-performing security standards. For more details, refer to DataDome Privacy Policy.

DataDome also requires touch event data to better understand and analyze user behavior, contributing to more precise detection. Use the code below to integrate this feature:

@Override
  public boolean dispatchTouchEvent(MotionEvent event) {
    dataDomeSDK.handleTouchEvent(event);
    return super.dispatchTouchEvent(event);
}

Test your integration

Use an user agent with the value BLOCKUA on your HTTP request to force a captcha display:

Request request = Request.newBuilder()
                    .header("User-Agent", "BLOCKUA")
                    .url(url)
                    .build();

Between two tests, clear your cookies to present additional challenge.

IMPORTANT NOTE
Make sure the BLOCKUA user agent is not used in production. Otherwise, the Captcha will appear at least once for each user.