SDK iOS

This guide describes how to integrate the DataDome SDK in your iOS application.

VersionVersion LicenseLicense PlatformPlatform

The DataDome iOS SDK is a lightweight SDK written in Swift 5. The module assumes the following roles once integrated into your app:

  • Intercepting and handling 403 responses blocked by DataDome. A captcha is displayed by the SDK and the failed requests are retried automatically when the captcha is resolved.
  • Managing cookies in the app. The DataDome cookie is a session token generated per request. The SDK stores and signs automatically all requests with the DataDome cookie.
  • Collecting behavioural signals in the app to understand how real users use your app. Those collected data are used to improve our detection ML models. Please refer to this section for more information on what piece of data we collect in your app

Install the SDK

Swift package manager

DataDomeSDK is available on Swift Package Manager. To get the SDK integrated in your project, follow the steps below:

  1. Go to "Xcode > File > Swift Packages > Add Package Dependency", select the target where 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 in your Podfile:

pod "DataDomeSDK"

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

Note
Please note that starting with SDK version 2.5.0, we use the XCFramework format. Old CocoaPods versions don't handle this new format well. Please make sure you are using CocoaPods version 1.10 or later to avoid any linking issue.

Carthage

DataDomeSDK is available on Carthage. To get the SDK integrated in your project, follow the steps below:

  1. Create a Cartfile if not already created.
  2. Add the following dependency in your project Cartfile
binary "https://package.datadome.co/ios/DataDomeSDK.json"
  1. Run the following command to fetch and integrate the package
carthage update --use-xcframeworks

Note
Please note that Carthage supports the XCFramework format starting from version 0.38.0. With SDK version 2.5.0, we use the XCFramework format. Old Carthage builds don't handle this new format well. Please make sure you are using Carthage version 0.38.0 or later to avoid any linking issue.

Configure the SDK

Set the DataDome Key

  1. Run your application. It will crash and return the following log:
    Fatal error: [DataDome] Missing DataDomeKey (Your client side key) in your Info.plist
  2. In your Info.plist, add a new entry with String type, use DataDomeKey as "key" and your actual client side key as "value".
  3. Now you can run the app without crashing. You should get a log confirming the SDK is running:
    [DataDome] Version x.y.z
    Congrats, the DataDome framework is now properly integrated.

Use the Logger (Optional)

If you need to view the logs produced by the framework, you can configure the log level to control the detail level in the 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:

verboseEverything is logged
infoInfo messages, warnings and errors are shown
warningOnly warning and error messages are printed
errorOnly errors are printed
noneSilent mode (default)

Share cookies between native and web (Optional)

If you are using WKWebView in your application to display web pages that are protected with DataDome, you can share the generated cookie by resolving a Captcha on the native part of the app, therefore a second Captcha won't be 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, else it returns nothing if there was no Captcha stored.

If your web page is displayed before the app sends any request natively, you can 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)

Use the DataDome SDK

Depending on the networking layer you setup for your application, choose one or multiple integrations from the list below:

Sample App

Below is a sample app demonstrating the implementation of DataDomeSDK with different integration modes depending on the networking library used.

App Privacy Details

Starting from December 8th, 2020, Apple is requesting that you disclose any data type you are collecting in your app including data collected by third party libraries you integrate in the app.
This will help users understand an app’s privacy practices before they download the app on any Apple platform. On each app’s product page, users can learn about some of the data types the app may collect, and whether that data is linked to them or used to track them.

In order to help you fill out Apple’s Privacy Practices Questionnaire, please refer to the following document, to find all the needed information regarding data collection practices of the DataDome SDK that you might integrate in your app.