v3
Installation
Swift Package Manager
DataDomeSDK is available on Swift Package Manager. To add the SDK to your project:
- In Xcode, open File ▸ Swift Packages ▸ Add Package Dependency, and select the target that uses DataDome.
- Paste this Git URL in the search bar:
https://github.com/DataDome/datadome-ios-package. - 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 CarthageSince 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:
- If your project does not have a Cartfile, create one.
- Add this dependency to your Cartfile:
binary "https://raw.githubusercontent.com/DataDome/datadome-ios-package/refs/heads/master/DataDomeSDK.json" ~> 3.6.2- Run this command to fetch and integrate the package:
carthage update --use-xcframeworksConfiguration
Option 1: From your application's Info.plist
Info.plist-
Get your DataDome Client-Side Key from your DataDome dashboard.
-
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
-
Get your DataDome Client-Side Key from your DataDome dashboard.
-
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) -> URLSessionDataTaskfunc 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)
-> URLSessionDataTaskfunc 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 onlyAlso set
DataDomeSDK.bypassHTTPAccept = trueto 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
Accept header overrideIf 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 toJSON
Set the language of the DataDome response pages
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")Updated about 10 hours ago

