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)
					.listener(dataDomeSDKListener)

        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

Note:

From Android SDK 1.9.1 when Captcha page is canceled by pressing the back or home button, the blocked response is forwarded to the application.
The next call is expected to be blocked with Captcha display as well since the navigation legitimacy is not confirmed yet.
If your application code base is handling the 403 status-code response, please make sure you choose the appropriate BackBehaviour to not harm the user experience.
(e.g: if you are displaying an alert popup or error page in case of 403, make sure that the user is able to perform a new request)

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() {

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

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

	@Override
	public void onCaptchaSuccess() {
		// Response After Captcha Success
	}

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

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

	@CallSuper
	public void onCaptchaDismissed() {
		// Response when captcha disapear
	}
}

SFCC module integration

Some integration changes will be needed for SFCC users to ensure the 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()
                    .followRedirects(false)
                    .followSslRedirects(false)

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