Flutter Plugin - Dio Integration

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, add the datadome_flutter_dio dependency to your pubspec.yaml file as shown in the following

dependencies:
  datadome_flutter_dio: ^3.0.0
  flutter:
    sdk: flutter

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

flutter create -i swift -a kotlin

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.

Gesture detection

In order to improve our detection, our mobile SDK collects some extra signals about device model, application version, and some gestural behaviors.
To enable gesture event collection, you need to call DataDome GestureDetection widget in your application view

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        home: GestureDetection(
          child: Scaffold(
              appBar: AppBar(
                title: const Text('DataDome example app'),
              ),
              body: Center(
                 child:
                      // your view widgets
              ),
          )
        ),
    );
  }

Share cookie between application and webview context

If your application also uses webviews, 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 application to webview context

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 application context

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());
  }
}

Flutter Dio - Manual integration

For customers who prefer to handle captcha display themselves, you can use a manual integration.
Captcha display and dismiss will be called through a callback you define on your side, and pass them as parameters to the DataDomeInterceptor.withCallback initialization.

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

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

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