iOS SDKs

Introduction

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

The SDKs are responsible for:

• Displaying a Challenge when needed
• Retrying blocked requests once the Challenge is resolved
• Collecting behavioral signals to improve your service protection

Installation

Refer to the documentation of the specific SDK needed according to your choice of network library.

• UrlSession
• Alamofire
• Apollo

Configuration

Option 1: From your application's Info.plist

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

2. Copy this plist extract and fill it with your configuration.

    <key>DataDome</key>
    <dict>
        <key>Origin</key>
        <string>https://example.com</string>    // Your API's origin
    </dict>
    <key>DataDomeKey</key>
    <string>KEY</string>                        // Your DataDome Client Side Key
    <key>DataDomeProxyEnabled</key>
    <false/>                                    // `true` to use the DataDome proxy (set to `false` when integrating our Alamofire or our Apollo SDK)

You can now start working with the SDK.

Starting with version 3.8.0 of the SDK, you can push the configuration early to the SDK. This will allow the SDK to start collecting signals earlier and enhance the detection.
To do so, add this code at the very begining of your application's lifecycle. With UIKit, application(_: didFinishLaunchingWithOptions) is a good place to do it.

do {
    let dataDomeConfiguration = try DataDomeSDK.Configuration.configurationFromBundle()
    DataDomeSDK.configure(withConfiguration: dataDomeConfiguration)
} catch {

}

Option 2: From code

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

2. Add the following code at the very begining of your application's lifecycle. With UIKit, application(_: didFinishLaunchingWithOptions) is a good place to do it.

let dataDomeConfiguration = DataDomeSDK.Configuration(origin: URL(string: "https://example.com")!,  // Your API's origin
                                                      clientKey: "KEY")                             // Your DataDome Client Side Key
DataDomeSDK.configure(withConfiguration: dataDomeConfiguration)

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.