OkHttp Integration

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

DataDome Interceptor Integration

DataDome provides a simple implementation of the SDK through the OkHttp Interceptor:

import android.app.Application;

class MainActivity extends AppCompatActivity {

    private DataDomeSDK.Builder dataDomeSDK;

    public void makeRequest(){
        dataDomeSDK = DataDomeSDK.with(getApplication(), "Client_Side_Key", BuildConfig.VERSION_NAME)

        OkHttpClient.Builder builder = new OkHttpClient.Builder();
        builder.addInterceptor(new DataDomeInterceptor(getApplication(), dataDomeSDK));
        OkHttpClient client = builder.build();


It is possible to customize some parameters of the SDK, using the builder:

  • .with(Application application, String dataDomeSDKKey, String appVersion): create a new Builder
  • .listener(DataDomeSDKListener listener): set the DataDomeSDKListener associated with the SDK instance
  • .agent(String userAgent): set a custom UA
  • .bypassAcceptHeader(Boolean bypassAcceptHeader): set if you will allow bypassing the DataDome Accept Header (refer to Optional Settings)
  • .backBehaviour(BackBehaviour behaviour): set a custom behavior for the back action on the Captcha page

Available BackBehaviour options are:

  • GO_BACKGROUND (default one): the Back button makes your app move to the background. Users can't go back if they don't pass the Captcha test (recommended)
  • BLOCKED: the Back button has no effect. Users can't go back if they don't pass the Captcha test
  • GO_BACK: the Back button makes the app go back and cancel the call

Where to place the DataDome Interceptor vs Existing interceptors

The DataDome interceptor will react only to responses with 403 response code. If you have an interceptor that may break the interceptors chain when receiving 403 response code, consider adding it after the DataDome Interceptor. Otherwise, the DataDome SDK will not receive the 403 code and will not be able to display the captcha and unblock the user.

Datadome Listener

The DataDome Listener is optional and provides you with another way to get more information concerning request handling by the SDK with the Captcha lifecycle.

Below is the list of all the listeners provided by the DataDome SDK:

DataDomeSDKListener dataDomeSDKListener = new DataDomeSDKListener() {

    public void onError(final int errno, final String error) {
        // handle DataDome Error

    public void onHangOnRequest(final int code) {
        // Waiting for response

    public void onCaptchaSuccess() {
        // Response After Captcha Success

    public void onCaptchaLoaded() {
        // Response when captcha is loaded

    public void onCaptchaCancelled() {
        // Response when captcha is cancelled

    public void onCaptchaDismissed() {
        // Response when captcha disapear

Use a custom user agent

When using the method .agent("Header value"), the SDK will add a User-Agent header with the provided value.
Make sure that in your list of interceptors, you are not updating and overriding this value with another one.
You can consider putting any interceptors that updates the User-Agent before the DataDome Interceptor, so that the .agent() method can have the last say.

SFCC module integration

Some integration changes will be needed for SFCC users to ensure captcha display redirection.
1- Enable bypassAcceptHeader at the SDK initialization

dataDomeSdk = DataDomeSDK
                .with(application, BuildConfig.DATADOME_SDK_KEY, BuildConfig.VERSION_NAME)
                .listener(dataDomeSDKListener) // optional 
                .manualListener(dataDomeSDKManualIntegrationListener) // optional
                .bypassAcceptHeader(true) // must set to true for SFCC

2- Disable Okhttp client redirection

val builder = OkHttpClient.Builder()

For more details here is the link to the PR: https://github.com/DataDome/SDK_Android/pull/79