Manual Integration

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

The manual integration is simple, involving the steps below:

  1. SDK initialization
    Initialize the SDK
  2. Getting headers
    Add DataDome headers to your request headers
  3. Verifying the Response
    When the request is completed, verify if it is a DataDome Response or not
  4. Handling DataDome Response
    If it is a DataDome response, handle it using the SDK
  5. Manual Listener
    The listener that helps in response handling
This integration is useful in some specific cases:
  • Integration in a complex architecture
  • Integration in a project with several different HTTP clients or network layers
  • Integration in a project using another HTTP client that is not yet supported
However, we strongly recommend using OkHttp integration whenever possible.

1 - DataDome SDK Initialization

First of all, you need to initialize the SDK with the builder.

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

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

The 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
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, DataDomeConfiguration(URL("https://example.com")))
											.activateDatadomeLogger(true)

    }

    [...]
    
}

2 - DataDome Headers

After SDK initialization, add the DataDome headers to your request headers:

import android.app.Application;

class MainActivity extends AppCompatActivity {

	public void makeRequest() {

		HashMap<String, String> headers = new HashMap<String, String>()
		headers = dataDomeSdk.addDataDomeHeaders(headers)

	}
}

3 - DataDome Verify Response

After the request is completed, the first step is to verify if the response is a DataDome response or not, using the verifyResponse method:

import android.app.Application;

class MainActivity extends AppCompatActivity {

	public void makeRequest() {

		if (dataDomeSdk.verifyResponse(url, responseHeaders, responseCode)) {
			// DataDome response
		} else {
			// Normal response
		}
	}

}

4 - DataDome Handle Response

When there is a DataDome response, you need to call handleResponse from the SDK to properly handle and manage the DataDome response and the Captcha.

The url parameter is the endpoint your are requesting.

The parameter requestId is optional. The goal of this parameter is to track the requests for future retry with the DataDomeSDKManualIntegrationListener.

import android.app.Application;

class MainActivity extends AppCompatActivity {

	public void makeRequest() {

		if (dataDomeSdk.verifyResponse(url, responseHeaders, responseCode)) {
			// DataDome response
			dataDomeSdk.handleResponse(requestId, responseHeaders, responseCode, responseData, domain)
		} else {
			// Normal response
		}
	}

}

5 - Manual Listener

With the manual integration, it is important to add the manualListener to be able to retry or get information concerning the response handling:

  • .manualListener(DataDomeSDKManualIntegrationListener): each requestId in listener is optional. It depends if you called the response handling (using the handleResponse method) with the requestId parameter or not.
import android.app.Application;

class MainActivity extends AppCompatActivity {
  
	 private var dataDomeSDKManualIntegrationListener: DataDomeSDKManualIntegrationListener = object: DataDomeSDKManualIntegrationListener() {

        override fun onRequestInProgress(requestId: Int?) {
            // Another request is already handled
        }

        override fun onComplete(requestId: Int?) {
            // Captcha is dismissed after the challenge was Successfully solved
        }

        override fun onError(requestId: Int?, errorMessage: String?) {
            // Error during the handling of the request
        }

        override fun onDismiss() {
            // Captcha is dismissed and the request was handled
        }

        override fun willDisplayCaptcha() {
            // Captcha will be displayed
        }
    }
  
    private DataDomeSDK.Builder dataDomeSDK;

    public void makeRequest(){
      	dataDomeSDK = DataDomeSDK.with(getApplication(), "Client_Side_Key", BuildConfig.VERSION_NAME, DataDomeConfiguration(URL("https://example.com")))
					.manualListener(dataDomeSDKManualIntegrationListener)

    }

    [...]
    
}