DataDome Flutter - Dio Integration

DataDome Flutter Dio plugin is an flutter plugin to support DataDome protection using Dio http client. The plugin provides an interceptor that filters and validates all requests to ensure your app networking layer is protected with DataDome.

Displaying the captcha, managing the cookies and handling the event tracker are all managed by the plugin.

Install the plugin

To install the plugin, run the following command:

flutter pub add datadome_flutter_dio

Note: Make sure your project does support Swift/Kotlin. If not, enable Swift/Kotlin for your Flutter project by using the following command:

# Replace project_name with your project's directory name
flutter create -i swift -a kotlin project_name

Usage

The DataDome Flutter Dio plugin provides an interceptor to be configured with your existing Dio instance. The plugin will intercept all requests performed by Dio, catch any signal from the DataDome remote protection module, display a captcha if relevent and then retry the failed requests. This is all managed by the plugin.

Import the DataDome Interceptor

You can import the DataDome Interceptor class using the following statement

import 'package:datadome_flutter_dio/datadome_interceptor.dart';

Initialize the DataDome Interceptor

Make sure you create an instance of the DataDome interceptor by passing:

• The DataDome client side key
• The Dio client
• The context to be used to display a captcha eventually

Once created, you can add the interceptor to Dio

var dio = Dio();
dio.interceptors.add(DataDomeInterceptor('YOUR_CLIENT_SIDE_KEY', dio, context));

Force a captcha display

To test and validate your integration, use a specific header to force the DataDome remote protection module to block the request and force the plugin to display the captcha. We use the User-Agent header with the value BLOCKUA to hint the remote module to block the request. Please note that the captcha is displayed once and then the generated cookie is stored locally.

Here a sample code to perform a GET request while forcing a captcha display

var dio = Dio();
dio.interceptors.add(DataDomeInterceptor('YOUR_CLIENT_SIDE_KEY', dio, context));
try {
  var response = await dio.get(
  				'https://datadome.co/wp-json', 
  				options: Options(headers: {'User-Agent': 'BLOCKUA'})
  );
  print(response);
} catch (e) {
  print(e);
}

IMPORTANT Do not leave this header in production. This will lead all users to see a captcha at least once.

Configure the logger

The DataDome flutter plugin for Dio comes with a logger. You can configure the logger to print out log messages to the console according to the following log levels: By default, the plugin is completely silent (log level none)

Level	Description
verbose	Everything is logged
info	Info messages, warnings and errors are shown
warning	Only warning and errors messages are printed
error	Only errors are printed
none	Silent mode (default)

To set the log level, use the following syntax

DataDomeLogger.setLogLevel(LogLevel.warning);

Manual integration

A manual integration mode is available if you need finer control on how captcha pages are displayed. Events for captcha display and dismissal will be dispatched through a callback defined in your own code, and passed as a parameter of the DataDomeInterceptor.withCallback initialization function.

DataDomeInterceptor dataDomeInterceptor = DataDomeInterceptor.withCallback(datadome_client_key, dio, (widget) { displayCaptcha(widget); }, () { dismissCaptcha(); });

Here are examples of captcha page display and captcha page dismiss callback functions

The view parameter represents the captcha page we handle in Flutter SDK.

void displayCaptcha(Widget view) {
  showGeneralDialog(
    context: context,
    barrierDismissible: false,
    pageBuilder: (context, __, ___) {
      return view;
    },
  );
}

void dismissCaptcha() {
  Navigator.pop(context);
}

Share cookie between native and webview code

If your application uses both native and webview pages, we recommend you to share DataDome cookies between both environments. This will avoid your users losing the session they have with DataDome every time the application switches to a webview page.

From native to webview

First retrieve the stored DataDome cookie with the getDataDomeCookie method as shown below:

String cookieValue = await dataDomeInterceptor.getDataDomeCookie();

Then, add this cookie value to your cookie manager. The sample below assumes the usage of the WebviewCookieManager from the webview_cookie_manager package.

// Get stored DataDome cookie
String cookieValue = await dataDomeInterceptor.getDataDomeCookie();

var wvCookie = Cookie.fromSetCookieValue(cookieValue);
// Add DataDome cookie to cookie manager
await cookieManager.setCookies([wvCookie], origin: test_url);

From webview to native

Store the new DataDome cookie value from your webview by calling setDataDomeCookie method:

final cookies = await cookieManager.getCookies(url);
    for (var item in cookies) {
    if(item.name == "datadome") {
        // Update DataDome cookie store with the new cookie value.
        dataDomeInterceptor.setDataDomeCookie(item.toString());
    }
}

Libraries

captcha_page

datadome_dio

datadome_interceptor

datadome_logger

retriable_request

tracking/event_data

tracking/event_tracker

tracking/gesture_detection