iOS SDK

Introduction

Our SDKs are meant to facilitate the integration of our services in your iOS applications.

The SDKs are responsible for:

• Displaying a Captcha and other response pages when needed
• Retrying blocked requests once the Captcha is resolved
• Collecting behavioral signals to improve your service protection

Installation

To install the SDK, please refer to the documentation of the specific SDK needed according to your choice of network library.

• UrlSession
• Alamofire
• Apollo

Configuration

Add your DataDome Client-Side Key to your project

The first step to start working with our SDKs is to add your DataDome Client-Side Key to your project, otherwise the SDK will raise the following fatal error Fatal error: [DataDome] Missing DataDomeKey (Your client side key) in your Info.plist

First, get you DataDome Client-Side Key from https://app.datadome.co/dashboard/management/integrations?created=2

Then, add a field keyed DataDomeKey to your Info.plist file and set your DataDome Client-Side Key as the value.

    <key>DataDomeKey</key>
    <string>YOUR DATADOME CLIENT SIDE KEY</string>

You can now start working with the SDK.

Share cookies between your mobile app and your WebViews

If you are using WKWebView in your application to display web pages that are protected with DataDome, you will need to pass the cookie generated by resolving a Captcha to your Webview to avoid getting challenged more than once.

When presenting a WKWebView, get the cookie from the SDK and pass it to the webview:

import DataDomeSDK

if let cookie = DataDomeSDK.getCookie() {
  wkWebView.configuration.websiteDataStore.httpCookieStore.setCookie(cookie)
}

When you are done with the WKWebView, you also need to pass the cookie back to the SDK like this:

import DataDomeSDK

for cookie in await wkWebView.configuration.websiteDataStore.httpCookieStore.allCookies() {
    if cookie.name == "datadome" {
        DataDomeSDK.setCookie(cookie)
    }
}

Bypass the Accept header override

By default the DataDomeSDK will set the Accept header of your HTTP requests to application/json if it was empty.

If you want to bypass this override, you can set DataDomeSDK.bypassHTTPAccept to true.

DataDomeSDK.bypassHTTPAccept = true

⚠️

Doing so could cause the Captcha reponse to not be formatted in JSON, if this were to be the case, the Captcha page would not be displayed by the SDK. To avoid the issue, you can force our Captcha Response format to JSON from the backoffice: under Management > Protection and endpoints > open the contextual menu of the enpoint you want to edit (the 3 dots button) > Edit > set the Response Format to JSON

Set the language of the DataDome response pages

The SDK is in charge of displaying the DataDome response pages when needed. Those response pages come in the form of a Captcha page, a Hard Block page or a Device Check page.

By default those page language is the application language, if supported (see the list of supported languages)

If you prefer to force the language of those pages, you can do so by calling the setResponsePageLanguage(_:) methode of DataDomeSDK with a language code (as define in the RFC 7231 section 5.3.5)

DataDomeSDK.setResponsePageLanguage("jp")

Testing your integration

Forcing the presentation of a Captcha

To test that your integration is functional, you may want to try to display a Captcha.

To do so, set the User-Agent of your request to BLOCKUA, it will trigger a Captcha response from our detection layer and the SDK will display a Captcha. Between two tests, you will need to clear your cookies to present additional Captcha.