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

AreaBefore (DataDomeSDK 3.x)After (DataDomeURLSession 1.0.0)
DependencyDataDomeSDKDataDomeURLSession (pulls in CoreDataDome)
Package managerCocoaPods, Carthage, or SPMSPM only
Minimum iOS1115
ConfigurationDataDomeSDK.configure(withConfiguration:) (global)Create and inject a DataDome instance
Protectionautomatic (swizzling) or protectedDataTask on URLSessionSend requests through a ProtectedURLSession
Challenge presentationCaptchaDelegate (optional)Automatic, customizable with DataDomeChallengeDisplayConfiguration
Info.plistDataDomeKey, DataDomeProxyEnabled, DataDome › OriginDataDome › 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'
end

Then 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

  1. In Xcode, open File ▸ Add Package Dependencies… and enter:

    https://github.com/DataDome/datadome-urlsession-package.git
  2. Set the dependency rule to Up to Next Major Version starting at 1.0.0, and add the DataDomeURLSession library product to your app target. CoreDataDome is added automatically as a dependency.

  3. Raise your app target's Minimum Deployments to iOS 15.0+.

Step 2: Create a DataDome instance

Replace 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

If 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

Challenge 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)
ParameterDefaultDescription
isDismissiblefalseWhether 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.
windowLevelUIWindow.Level.alert + 1The 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 DataDomeSDKimport CoreDataDome and import DataDomeURLSession
DataDomeSDK.ConfigurationDataDomeConfiguration
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 a URLSession, DataDome responses pass through unprocessed: challenges are skipped and the request completes without retry.
  • Challenge and block pages are displayed automatically. CaptchaDelegate has been removed.
  • Challenges are locked by default. To let users close a challenge without resolving it, set isDismissible: true in a DataDomeChallengeDisplayConfiguration (CoreDataDome 1.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 a URLSessionDataTask): one request can span several underlying tasks when a challenge is retried. It offers resume() and cancel().
  • The Combine publisher fails with any Error, including DataDomeError. 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 DataDome instance and must be awaited, because DataDome is an actor. To clear the DataDome cookie, call await dataDome.unsafeClearCachedData().

Troubleshooting

SymptomResolution
Build error: "requires minimum platform version 15.0"Raise your app target's Minimum Deployments to iOS 15.0+.
configurationFromBundle() throws on launchYour Info.plist still uses DataDomeKey. Migrate it (Step 3), or use DataDomeConfiguration(clientKey:).
Requests are challenged, but no challenge is displayedThe 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).

Did this page help you?