DataDome iOS SDK 2.0

VersionVersion LicenseLicense PlatformPlatform

Install

Swift package manager

DataDomeSDK is available on Swift Package Manager. To get the SDK integrated to your project:

  1. In Xcode > File > Swift Packages > Add Package Dependency, select your target in which to integrate DataDome.
  2. Paste the following git url in the search bar https://github.com/DataDome/datadome-ios-package
  3. Select DataDomeSDK and press Add.

Cocoapods

Alternatively, you can get the DataDomeSDK on CocoaPods. Simply add the following line to your Podfile:

pod "DataDomeSDK"

Run pod install to download and integrate the framework to your project.

Note
Please note that starting from version 2.5.0 of the SDK, we use the XCFramework format. Old versions of Cocoapods poorly handle this new format. Please make sure to use Cocoapods version 1.10 or later to avoid any linking issue that may occur.

Getting Started

  1. Run your application. It is going to crash with the following log
Fatal error: [DataDome] Missing DataDomeKey (Your client side key) in your Info.plist
  1. In your Info.plist, add a new entry with String type, use DataDomeKey as key and your actual client side key as value.
  2. You can run now the app, it won't crash. You should see a log confirming the SDK is running
[DataDome] Version x.y.z

Congrats, the DataDome framework is well integrated

Logging

If you need to see the logs produced by the framework, you can set the log level to control the detail of logs you get

import DataDomeSDK
DataDomeSDK.setLogLevel(level: .verbose)

By default, the framework is completely silent.

The following table contains different logging levels that you may consider using

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)

Force a captcha display

You can simulate a captcha display using the framework by providing a user agent with the value BLOCKUA

To do so:

  1. Edit your app scheme
  2. Under Run (Debug) > Arguments > Environment Variables, create a new variable
  3. Set the name to DATADOME_USER_AGENT and the value to BLOCKUA

The DataDome framework will inject the specified user agent in the requests the app will be sending. Using the BLOCKUA user agent value will hint our remote protection module installed on your servers to treat this request as if it is coming from a bot. Which will block it with a captcha response.

Since the DataDome framework retains the cookies after resolving the captcha, this test can be done only the first time you used the BLOCKUA user agent. To reproduce the test case, you can use the following code snippet to manually clear the cookies stored in your app

for cookie in HTTPCookieStorage.shared.cookies ?? [] {
    HTTPCookieStorage.shared.deleteCookie(cookie)
}

Share cookies between native and web

If you are using WKWebView in your application to display web pages that are protected with DataDome, you can share the cookie generated by resolving a captcha on the native part of the app so that a second captcha is not required on the web-based part of the app.
To share the DataDome cookie from the SDK to your WKWebView instance, use the following api

import DataDomeSDK

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

The getCookie api returns the stored captcha generated by the last resolved captcha or nil otherwise.

Now if your web page displays before the app send natively any request, you would consider providing the cookie stored by your web view after resolving the captcha on the web view side. Alternatively, if you need to store a cookie, use the following api

import DataDomeSDK

DataDomeSDK.setCookie(cookie: cookie)

Disable method swizzling

The DataDome Framework is using method swizzling to setup a proxy listening to all URLRequests performed by the app. The framework will then detect automatically blocked requests, lookup dynamically the top view controller in your app hierarchy and attach a captcha view controller to it. Once resolved, the framework will dismiss the captcha view controller and retry the blocked request with a new generate cookie. All this is done under the hood.

If you want to disable the method swizzling and manually tell the framework which request to monitor instead of monitoring all the traffic or / and you want to manually present and dismiss the captcha controller, please consider the following steps:

  1. In your Info.plist, add a new entry with Boolean type, use DataDomeProxyEnabled as key and NO as value. This will disable method swizzling in the framework.
  2. For each request to protect with DataDome, use the following methods to create the data task
func protectedDataTask(with url: URL,
                       captchaDelegate: CaptchaDelegate?,
                       completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) 
-> URLSessionDataTask
func protectedDataTask(with request: URLSessionRequest,
                       captchaDelegate: CaptchaDelegate?,
                       completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) 
-> URLSessionDataTask

Only the URLSessionDataTasks created by the above two methods are monitored and protected by DataDome.

Here a sample code to create and execute a data task

import DataDomeSDK


guard let url = URL(string: "https://datadome.co") else {
    return
}

let task = URLSession.shared.protectedDataTask(with: url, captchaDelegate: self, completionHandler: { _, _, _ in
    print("Request completed")
})
        
task.resume()

To manually manage the presentation of the captcha view controller, implement the CaptchaDelegate protocol

import DataDomeSDK

extension MyViewController: CaptchaDelegate {
    func present(captchaController controller: UIViewController) {
        self.navigationController?.present(controller, animated: true, completion: nil)
    }
    
    func dismiss(captchaController controller: UIViewController) {
        controller.dismiss(animated: true, completion: nil)
    }
}

Using Alamofire / Moya

If you are using Alamofire or Moya to build your app's networking layer, we have you covered.
Install the DataDome Alamofire plugin to protect your requests using the DataDome SDK

To install the plugin, use the following Cocoapods instruction

pod "DataDomeAlamofire"

Make sure method swizzling for URLSession is disabled to avoid any interference with Alamofire's under the hood URLSession usage.
In your Info.plist, add a new entry with Boolean type, use DataDomeProxyEnabled as key and NO as value. This will disable method swizzling in the framework.

Create your Alamofire Session Manager like in the following example

import DataDomeAlamofire

let configuration = URLSessionConfiguration.default
configuration.headers = .default
configuration.httpCookieStorage = HTTPCookieStorage.shared
        
let dataDome = AlamofireInterceptor()
let interceptor = Interceptor(adapter: dataDome.sessionAdapter, 
                              retrier: dataDome.sessionRetrier)
 
let alamofireSessionManager = Session(configuration: configuration, 
                                      interceptor: interceptor)

The rest of your app won't change, only make sure to use the created alamofireSessionManager to perform your requests.

Updated 2 months ago

DataDome iOS SDK 2.0


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.