How to migrate from DataDomeSDK v3
The URLSession integration used to ship inside the legacy DataDomeSDK (3.x). It is now a dedicated package, DataDomeURLSession, built on top of the new CoreDataDome SDK. This is a breaking change.
The main difference: DataDomeSDK could handle the DataDome responses of every URLSession call automatically by swizzling URLSession methods. DataDomeURLSession does not. Every call to an endpoint protected by DataDome must now be sent through a ProtectedURLSession.
This guide lists exactly what you need to change. For a fresh integration, see iOS + URLSession.
Requirements
- iOS 15+ (previously iOS 11)
- Xcode 26+, which Apple requires for App Store Connect uploads since April 28, 2026
- Swift Package Manager (CocoaPods and Carthage support has been removed)
- A DataDome client-side key, available in your DataDome dashboard
At a glance
| Area | Before (DataDomeSDK 3.x) | After (DataDomeURLSession 1.0.0) |
|---|---|---|
| Dependency | DataDomeSDK | DataDomeURLSession (pulls in CoreDataDome) |
| Package manager | CocoaPods, Carthage, or SPM | SPM only |
| Minimum iOS | 11 | 15 |
| Configuration | DataDomeSDK.configure(withConfiguration:) (global) | Create and inject a DataDome instance |
| Protection | automatic (swizzling) or protectedDataTask on URLSession | Send requests through a ProtectedURLSession |
| Challenge presentation | CaptchaDelegate (optional) | Automatic, customizable with DataDomeChallengeDisplayConfiguration |
| Info.plist | DataDomeKey, DataDomeProxyEnabled, DataDome › Origin | DataDome › ClientSideKey, DataDome › Domain |
Step 1: Update the dependency
Remove DataDomeSDK
If you integrated DataDomeSDK with CocoaPods, remove it from your Podfile:
target 'YourApp' do
# ❌ Remove this line
pod 'DataDomeSDK'
endThen run pod install, or pod deintegrate if DataDomeSDK was your only pod.
If you integrated DataDomeSDK with Swift Package Manager, remove the datadome-ios-package package in Xcode, in your project's Package Dependencies tab.
If you integrated DataDomeSDK with Carthage, remove the DataDomeSDK.json line from your Cartfile, then remove the DataDomeSDK.xcframework from your target.
Add DataDomeURLSession
-
In Xcode, open File ▸ Add Package Dependencies… and enter:
https://github.com/DataDome/datadome-urlsession-package.git -
Set the dependency rule to Up to Next Major Version starting at
1.0.0, and add theDataDomeURLSessionlibrary product to your app target.CoreDataDomeis added automatically as a dependency. -
Raise your app target's Minimum Deployments to iOS 15.0+.
Step 2: Create a DataDome instance
DataDome instanceReplace the global configuration with one DataDome instance, created once and reused for the lifetime of your app. It is an actor and is safe to share across tasks.
Before
import DataDomeSDK
let configuration = try DataDomeSDK.Configuration.configurationFromBundle()
// or: DataDomeSDK.Configuration(clientKey: "YOUR_DATADOME_CLIENT_SIDE_KEY", origin: URL(string: "https://your-domain.com"))
DataDomeSDK.configure(withConfiguration: configuration)After
import CoreDataDome
import DataDomeURLSession
let configuration = try DataDomeConfiguration.configurationFromBundle()
// or: DataDomeConfiguration(clientKey: "YOUR_DATADOME_CLIENT_SIDE_KEY", clientDomain: URL(string: "https://your-domain.com"))
let dataDome = DataDome(configuration: configuration)Keep a reference to dataDome: you need it to create a ProtectedURLSession in Step 4.
Step 3: Update your Info.plist
This step only applies if you read your configuration from the Info.plist, with DataDomeSDK.Configuration.configurationFromBundle() before and DataDomeConfiguration.configurationFromBundle() after. If you create your configuration programmatically, only remove DataDomeProxyEnabled.
The DataDomeKey string is replaced by a ClientSideKey entry in the DataDome dictionary. The optional Origin entry is renamed Domain.
Before
<key>DataDomeKey</key>
<string>YOUR_DATADOME_CLIENT_SIDE_KEY</string>
<key>DataDomeProxyEnabled</key>
<false/>
<key>DataDome</key>
<dict>
<key>Origin</key>
<string>https://your-domain.com</string>
</dict>After
<key>DataDome</key>
<dict>
<key>ClientSideKey</key>
<string>YOUR_DATADOME_CLIENT_SIDE_KEY</string>
<!-- Optional: your protected domain -->
<key>Domain</key>
<string>https://your-domain.com</string>
</dict>Remove DataDomeProxyEnabled: swizzling has been removed.
Step 4: Send requests through ProtectedURLSession
ProtectedURLSessionIf you relied on swizzling, your plain URLSession calls bypass DataDome response handling. Route every call to an endpoint protected by DataDome through a ProtectedURLSession, which mirrors the URLSession API:
let session = URLSession.shared.protected(by: dataDome)
// or: ProtectedURLSession(dataDome: dataDome)To use a custom session, wrap it the same way: mySession.protected(by: dataDome).
Completion handlers
Before
// Handled implicitly by swizzling
let task = URLSession.shared.dataTask(with: request) { data, response, error in }
task.resume()
// Or handled explicitly
let task = URLSession.shared.protectedDataTask(withRequest: request, captchaDelegate: self) { data, response, error in }
task.resume()After
let task = session.dataTask(with: request) { data, response, error in }
task.resume()async/await
Before
let (data, response) = try await URLSession.shared.protectedDataTask(withRequest: request, captchaDelegate: nil)After
let (data, response) = try await session.data(for: request)Combine
Before
URLSession.shared
.protectedDataTaskPublisher(forRequest: request, captchaDelegate: nil)
.sink(receiveCompletion: { _ in }, receiveValue: { response in })
.store(in: &cancellables)After
session.dataTaskPublisher(for: request)
.sink(receiveCompletion: { _ in }, receiveValue: { data, response in })
.store(in: &cancellables)Step 5: Remove your CaptchaDelegate
CaptchaDelegateChallenge and block pages are now displayed automatically by the SDK. Remove your CaptchaDelegate conformance and the captchaDelegate: arguments.
Before
import DataDomeSDK
extension MyViewController: CaptchaDelegate {
func present(captchaController controller: UIViewController) {
navigationController?.present(controller, animated: true, completion: nil)
}
func dismiss(captchaController controller: UIViewController) {
controller.dismiss(animated: true, completion: nil)
}
}After
The SDK displays challenges automatically in its own window, above your app's windows.
Customize how challenges are displayed
With CaptchaDelegate, you controlled where and how the challenge was presented. With CoreDataDome 1.1.0+, you customize the display with a DataDomeChallengeDisplayConfiguration, passed to DataDomeConfiguration:
import CoreDataDome
let configuration = DataDomeConfiguration(
clientKey: "YOUR_DATADOME_CLIENT_SIDE_KEY",
challengeDisplayConfiguration: DataDomeChallengeDisplayConfiguration(
isDismissible: true,
windowLevel: DataDomeChallengeDisplayConfiguration.defaultWindowLevel
)
)
let dataDome = DataDome(configuration: configuration)| Parameter | Default | Description |
|---|---|---|
isDismissible | false | Whether you can close a challenge without resolving it. The original response is returned and the request completes without retry. Invisible challenges show nothing to close. |
windowLevel | UIWindow.Level.alert + 1 | The level of the window challenges are displayed in. Raise it if your app displays its own windows above the alert level. System windows, such as permission prompts, always remain visible. |
Both parameters are optional. Without a DataDomeChallengeDisplayConfiguration, challenges remain locked and display at the default window level. For more details, see Configure how challenges are displayed.
API mapping
| Removed or changed (old) | Replacement (new) |
|---|---|
import DataDomeSDK | import CoreDataDome and import DataDomeURLSession |
DataDomeSDK.Configuration | DataDomeConfiguration |
DataDomeSDK.Configuration(clientKey:origin:) | DataDomeConfiguration(clientKey:clientDomain:) |
DataDomeSDK.configure(withConfiguration:) | DataDome(configuration:) |
DataDomeSDK.setKey(_:) | (removed) use DataDomeConfiguration(clientKey:) |
Automatic handling of URLSession calls (swizzling) | Send requests through a ProtectedURLSession |
protectedDataTask(withURL:captchaDelegate:) (async) | data(from:) |
protectedDataTask(withRequest:captchaDelegate:) (async) | data(for:) |
protectedDataTask(withURL:captchaDelegate:completionHandler:) | dataTask(with:completionHandler:) |
protectedDataTask(withRequest:captchaDelegate:completionHandler:) | dataTask(with:completionHandler:) |
protectedDataTaskPublisher(forURL:captchaDelegate:) | dataTaskPublisher(for:) |
protectedDataTaskPublisher(forRequest:captchaDelegate:) | dataTaskPublisher(for:) |
CaptchaDelegate | (removed) challenges are displayed automatically; customize the display with DataDomeChallengeDisplayConfiguration (CoreDataDome 1.1.0+) |
DataDomeSDK.getCookie() | await dataDome.getCookie(forURL:) |
DataDomeSDK.setCookie(_:) | await dataDome.setCookie(_:) |
DataDomeSDK.setResponsePageLanguage(_:) | (not available) |
DataDomeSDK.setLogLevel(level:) | (removed) logs use OSLog, subsystem co.datadome.ios.core |
DataDomeSDK.bypassHTTPAccept | (removed) |
DataDomeKey (Info.plist) | DataDome › ClientSideKey |
DataDome › Origin (Info.plist) | DataDome › Domain |
DataDomeProxyEnabled (Info.plist) | (removed) |
The new request methods are called on a ProtectedURLSession, not on URLSession.
Behavioral changes
- Every call to an endpoint protected by DataDome must be sent through a
ProtectedURLSession. For requests sent directly on aURLSession, DataDome responses pass through unprocessed: challenges are skipped and the request completes without retry. - Challenge and block pages are displayed automatically.
CaptchaDelegatehas been removed. - Challenges are locked by default. To let users close a challenge without resolving it, set
isDismissible: truein aDataDomeChallengeDisplayConfiguration(CoreDataDome1.1.0+). A dismissed challenge returns the original response, and the request completes without retry. - Every response is checked by DataDome, whatever its status code.
- Completion-handler methods return a
ProtectedURLSessionTask(instead of aURLSessionDataTask): one request can span several underlying tasks when a challenge is retried. It offersresume()andcancel(). - The Combine publisher fails with
any Error, includingDataDomeError. The request starts when you subscribe, and cancelling the subscription cancels the request. - A block page throws
DataDomeError.blocked. - Upload, download, and streamed (
bytes) requests are now supported. - Cookie methods are called on the
DataDomeinstance and must be awaited, becauseDataDomeis anactor. To clear the DataDome cookie, callawait dataDome.unsafeClearCachedData().
Troubleshooting
| Symptom | Resolution |
|---|---|
| Build error: "requires minimum platform version 15.0" | Raise your app target's Minimum Deployments to iOS 15.0+. |
configurationFromBundle() throws on launch | Your Info.plist still uses DataDomeKey. Migrate it (Step 3), or use DataDomeConfiguration(clientKey:). |
| Requests are challenged, but no challenge is displayed | The request was sent on a plain URLSession. Send it through a ProtectedURLSession (Step 4). |
Cannot find type 'CaptchaDelegate' | CaptchaDelegate was removed. Delete your conformance (Step 5). |
Value of type 'URLSession' has no member 'protectedDataTask' | Create a ProtectedURLSession with protected(by:) and use the URLSession-style methods on it (Step 4). |
Updated about 10 hours ago

