The DataDome KMM SDK for Ktor is a lightweight library, designed to integrate DataDome into KMM applications using Ktor. It is published on Maven Central.

Requirements

Installation

Add the SDK dependency to your build.gradle.kts file:

dependencies {
    implementation("co.datadome.kmm:datadome-ktor:1.0.0")
}

Additional steps for iOS

This SDK depends on our native CoreDataDome SDKs for iOS and Android. The dependency is automatically added for Android but requires one additional step for iOS.

Add the following SPM dependency directly to the Application's Xcode project:

https://github.com/DataDome/mobile-package-ios-coredatadome.git

Learn more about how to add an SPM dependency to your Application on Apple website.

Configuration

Initialize the DataDome instance

1. Create a configuration object:

val dataDomeConfiguration = DataDomeConfiguration(clientKey = "YOUR_CLIENT_KEY", domain = null)

If your use case requires initializing a DataDome's session at launch, you can optionally specify the base URL of your app’s API domain using the domain parameter.

The domain should be the fully qualified URL of the API backend your app communicates with (for example, https://your_domain.com).

val dataDomeConfiguration = DataDomeConfiguration(clientKey = "YOUR_CLIENT_KEY", 
																									domain = "https://example.com")

2. Create the DataDome instance:

val dataDome = DataDome(configuration = dataDomeConfiguration)

3. Configure your Ktor HTTP Client:

Install both your dataDome instance AND the DataDomeCookieStorage inside your Ktor HTTPClient.

val client = HttpClient {
  install(dataDome)
}

Manage the DataDome session

The DataDome session is maintained via the datadome cookie.

You have a few option to handle it properly:

Option 1: Use the DataDomeCookieStorage alone

This option is best if you do not need to manage other cookies than the DataDome one. Just add the DataDomeCookieStorage before you install the interceptor.

val client = HttpClient {
    install(HttpCookies) {
      storage = DataDomeCookieStorage(dataDome)
    }

  install(dataDome)
}

Option 2: Use the DataDomeCookieStorage + your own storage

If you already have your own custom cookie storage, pass your own CookieStorage as an argument to the DataDomeCookieStorage.

val client = HttpClient {
    install(HttpCookies) {
      storage = DataDomeCookieStorage(dataDome, CustomCookiesStorage())
    }

  install(dataDome)
}

Option 3: Manually handle all cookie via the Cookie header

If you already manage your own cookies via the Cookie header, the DataDome SDK will intercept it and add or update the datadome cookie automatically. You do not need to install HttpCookies in that case.

Usage

After configuring DataDome, you can use Ktor to make Http calls as usual by calling client.get(endpoint) {}.

DataDome will intercept every requests and responses automatically and handle the display of potential challenges before retrying requests when required.

How to test

Test your integration by setting the UserAgent header to BLOCKUA.

This will force the display of a challenge when no DataDome session is available. To display another challenge, clear the DataDome session by removing the datadome cookie from the Cookie Storage.

client.get(endpoint) {
  headers {
    append(HttpHeaders.UserAgent, "BLOCKUA")
  }
}