Manual Integration

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

    }

    [...]
    
}

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, applicationContext)) {
			// 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, applicationContext)) {
			// DataDome response
			dataDomeSdk.handleResponse(requestId, responseHeaders, responseCode, responseData)
		} 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)
					.listener(dataDomeSDKListener)
					.manualListener(dataDomeSDKManualIntegrationListener)

    }

    [...]
    
}

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
	}
}

Force a Captcha display

You can simulate a Captcha display using the framework by providing a user agent with the value BLOCKUA.
You can pass this value while building the instance of DataDomeSDK using the following API:

dataDomeSDK = DataDomeSDK
        .with(getApplication(), "Client_Side_Key", BuildConfig.VERSION_NAME)
        .listener(DataDomeSDKListener)
        .agent("BLOCKUA");

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