v3

Version License Platform

Installation

Swift Package Manager

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

  1. In Xcode, open File ▸ Swift Packages ▸ Add Package Dependency, and select the target that uses DataDome.
  2. Paste this Git URL in the search bar: https://github.com/DataDome/datadome-ios-package.
  3. Select DataDomeSDK, then click Add.

CocoaPods

DataDomeSDK is available on CocoaPods. Add this line to your Podfile:

pod "DataDomeSDK"

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

Carthage

🚧

Dropping support for Carthage

Since February 1, 2025, new versions of this SDK are not released on Carthage. Use SPM instead.

DataDomeSDK is available on Carthage. To add the SDK to your project:

  1. If your project does not have a Cartfile, create one.
  2. Add this dependency to your Cartfile:
binary "https://raw.githubusercontent.com/DataDome/datadome-ios-package/refs/heads/master/DataDomeSDK.json" ~> 3.6.2
  1. Run this command to fetch and integrate the package:
carthage update --use-xcframeworks

Configuration

Option 1: From your application's Info.plist

  1. Get your DataDome Client-Side Key from your DataDome dashboard.

  2. Copy this extract to your Info.plist, and replace the values 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 enable swizzling (set it to false with the Alamofire or Apollo SDK) -->

The SDK is now ready to use.

From version 3.8.0, you can give the configuration to the SDK early. The SDK then starts to collect signals earlier, which improves the detection.

To do this, add this code at the start of your application lifecycle. With UIKit, add it to application(_:didFinishLaunchingWithOptions:).

do {
    let dataDomeConfiguration = try DataDomeSDK.Configuration.configurationFromBundle()
    DataDomeSDK.configure(withConfiguration: dataDomeConfiguration)
} catch {
    // Handle the missing or invalid configuration
}

Option 2: From code

  1. Get your DataDome Client-Side Key from your DataDome dashboard.

  2. Add this code at the start of your application lifecycle. With UIKit, add it to application(_:didFinishLaunchingWithOptions:).

let dataDomeConfiguration = DataDomeSDK.Configuration(clientKey: "KEY",                              // Your DataDome client-side key
                                                      origin: URL(string: "https://example.com"))  // Your API's origin (optional)
DataDomeSDK.configure(withConfiguration: dataDomeConfiguration)

Usage

Swizzling

The DataDomeSDK can intercept all the HTTP requests that these URLSession methods send:

  • func dataTask(with url: URL, completionHandler: @escaping @Sendable (Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask
  • func dataTask(with request: URLRequest, completionHandler: @escaping @Sendable (Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask

The SDK uses swizzling: it replaces the implementation of these methods with its own at runtime.

Swizzling is enabled by default. To protect all the HTTP requests that these methods send, you do not need to do anything else.

Manually protecting requests

To protect only some HTTP requests, first disable swizzling. Add this property to the Info.plist of your project:

    <key>DataDomeProxyEnabled</key>
    <false/>

Then, send each protected HTTP request with one of these DataDomeSDK methods:

func protectedDataTask(withURL url: URL,
                       captchaDelegate: CaptchaDelegate?,
                       completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) 
                        -> URLSessionDataTask
func protectedDataTask(withRequest request: URLRequest,
                       captchaDelegate: CaptchaDelegate?,
                       completionHandler: @escaping (Data?, URLResponse?, Error?) -> Void) 
                        -> URLSessionDataTask
    func protectedDataTask(withURL url: URL, 
                           captchaDelegate: CaptchaDelegate?) async throws 
                            -> (Data, URLResponse)
    func protectedDataTask(withRequest request: URLRequest, 
                           captchaDelegate: CaptchaDelegate?) async throws 
                            -> (Data, URLResponse)

The Captcha delegate

To manage the navigation of the CaptchaViewController, 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)
    }
}

Combine

If your app sends requests with Combine and DataTaskPublisher, use these APIs to create a DataTaskPublisher with the DataDome operators:

/// Provides a publisher with downstream DataDome operators
/// - Parameters:
///   - url: The url to be requested
///   - captchaDelegate: The captcha delegate
/// - Returns: A publisher with the DataDome operators
func protectedDataTaskPublisher(forURL url: URL,
                                captchaDelegate: CaptchaDelegate?)
    -> AnyPublisher<URLSession.DataTaskPublisher.Output, URLSession.DataTaskPublisher.Failure>

Or, with a URLRequest parameter:

/// Provides a publisher with downstream DataDome operators
/// - Parameters:
///   - request: The request to be processed
///   - captchaDelegate: The captcha delegate
/// - Returns: A publisher with the DataDome operators
func protectedDataTaskPublisher(forRequest request: URLRequest,
                                captchaDelegate: CaptchaDelegate?)
-> AnyPublisher<URLSession.DataTaskPublisher.Output, URLSession.DataTaskPublisher.Failure>

This example uses the protected DataDome publisher:

import DataDomeSDK

URLSession
.shared
.protectedDataTaskPublisher(forURL: url, captchaDelegate: nil)
.sink(receiveCompletion: { completion in
      switch completion {
        case .finished:
            break
        case .failure(let error):
            print(error.localizedDescription)
      }
}, receiveValue: { response in
     guard let httpResponse = response.response as? HTTPURLResponse else {
       print("Invalid response")
       return
     }

     print("Did receive response with code \(httpResponse.statusCode)")
})

You can use other operators to validate or transform the publisher or its elements. For more details, refer to the Apple documentation.

More

SFCC support

SFCC endpoints use different rules to show the captcha.

Implement this method of URLSessionTaskDelegate:

urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse, newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void)

If the path of the URL in the Location HTTP header contains a DDUser-Challenge component, return nil.

Example:

func urlSession(_ session: URLSession,
                task: URLSessionTask,
                willPerformHTTPRedirection response: HTTPURLResponse,
                newRequest request: URLRequest,
                completionHandler: @escaping (URLRequest?) -> Void) {
    if let location = response.value(forHTTPHeaderField: "location"),
        let url = URL(string: location),
        url.pathComponents.contains("DDUser-Challenge") {
        return completionHandler(nil)
    }

    return completionHandler(request)
}
🚧

On versions older than 3.6.0 only

Also set DataDomeSDK.bypassHTTPAccept = true to display the captcha correctly.

Share cookies between your mobile app and your WebViews

If you use a WKWebView to show web pages that DataDome protects, give the cookie of the solved captcha to the WebView. Otherwise, the user gets a new challenge in the WebView.

Before you show the WKWebView, get the cookie from the SDK and give it to the WebView:

import DataDomeSDK

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

After you close the WKWebView, give the cookie back to the SDK:

import DataDomeSDK

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

Bypass the Accept header override

Added in version 1.3.0 Deprecated with version 3.6.0

If the Accept header of an HTTP request is empty, the DataDomeSDK sets it to application/json by default.

To bypass this override, set DataDomeSDK.bypassHTTPAccept to true.

DataDomeSDK.bypassHTTPAccept = true
⚠️

With this option, the captcha response can be in a format other than JSON. The SDK then cannot show the captcha page. To prevent this problem, set the captcha response format to JSON in the dashboard: go to Management > Protection and endpoints > open the contextual menu of the endpoint you want to edit (the 3 dots button) > Edit > set the Response Format to JSON

Set the language of the DataDome response pages

Added in version 3.3.0

The SDK shows the DataDome response pages when necessary: the Captcha page, the Hard Block page, and the Device Check page.

By default, these pages use the language of the application, if DataDome supports it (refer to the list of supported languages).

To force the language of these pages, call DataDomeSDK.setResponsePageLanguage(_:) with a language code (see RFC 7231 section 5.3.5).

DataDomeSDK.setResponsePageLanguage("ja")

Did this page help you?