The migration from v1 to v2 represents a migration from a monolith SDK into a modular architecture. RUM, Trace, Logs, Session Replay, and so on each have individual modules, allowing you to integrate only what is needed into your application.

SDK v2 offers a unified API layout and naming alignment between the iOS SDK, the Android SDK, and other Datadog products.

SDK v2 enables the usage of Mobile Session Replay on Android and iOS applications.

The migration from v1 to v2 represents a migration from a monolith SDK into a modular architecture. RUM, Trace, Logs, Session Replay, and so on each have individual modules, allowing you to integrate only what is needed into your application.

SDK v2 offers a unified API layout and naming alignment between the iOS SDK, the Android SDK, and other Datadog products.

SDK v2 enables the usage of Mobile Session Replay on Android and iOS applications.

The migration from v1 to v2 comes with improved performance.

The migration from v1 to v2 comes with improved performance and additional features supplied by the v2 Native SDKs.

Artifacts are modularized in v2. Adopt the following artifacts:

• RUM: com.datadoghq:dd-sdk-android-rum:x.x.x
• Logs: com.datadoghq:dd-sdk-android-logs:x.x.x
• Trace: com.datadoghq:dd-sdk-android-trace:x.x.x
• Session Replay: com.datadoghq:dd-sdk-android-session-replay:x.x.x
• WebView Tracking: com.datadoghq:dd-sdk-android-webview:x.x.x
• OkHttp instrumentation: com.datadoghq:dd-sdk-android-okhttp:x.x.x

Note: If you use NDK Crash Reporting and WebView Tracking, you must add RUM and Logs artifacts to report events to RUM and Logs respectively.

Reference to the com.datadoghq:dd-sdk-android artifact should be removed from your Gradle build script, as this artifact doesn’t exist anymore.

Note: The Maven coordinates of all the other artifacts stay the same.

Should you encounter an error such as the following:

A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable
Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules kotlin-stdlib-1.8.10 (org.jetbrains.kotlin:kotlin-stdlib:1.8.10) and kotlin-stdlib-jdk8-1.7.20 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.20)

Add the following rules to your build script (more details in the relevant Stack Overflow issue):

dependencies {
    constraints {
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.8.10") {
            because("kotlin-stdlib-jdk7 is now a part of kotlin-stdlib")
        }
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.10") {
            because("kotlin-stdlib-jdk8 is now a part of kotlin-stdlib")
        }
    }
}

See the Android sample application for an example of how to set up the SDK.

Libraries are modularized in v2. Adopt the following libraries:

• DatadogCore
• DatadogLogs
• DatadogTrace
• DatadogSessionReplay
• DatadogRUM
• DatadogWebViewTracking

These come in addition to the existing DatadogCrashReporting and DatadogObjc.

let package = Package(
  ...
  dependencies: [
      .package(url: "https://github.com/DataDog/dd-sdk-ios", from: "2.0.0")
  ],
  targets: [
      .target(
          ...
          dependencies: [
              .product(name: "DatadogCore", package: "dd-sdk-ios"),
              .product(name: "DatadogLogs", package: "dd-sdk-ios"),
              .product(name: "DatadogTrace", package: "dd-sdk-ios"),
              .product(name: "DatadogSessionReplay", package: "dd-sdk-ios"),
              .product(name: "DatadogRUM", package: "dd-sdk-ios"),
              .product(name: "DatadogCrashReporting", package: "dd-sdk-ios"),
              .product(name: "DatadogWebViewTracking", package: "dd-sdk-ios"),
          ]
      ),
  ]
)

pod 'DatadogCore'
pod 'DatadogLogs'
pod 'DatadogTrace'
pod 'DatadogSessionReplay'
pod 'DatadogRUM'
pod 'DatadogCrashReporting'
pod 'DatadogWebViewTracking'
pod 'DatadogObjc'

github "DataDog/dd-sdk-ios"

DatadogInternal.xcframework
DatadogCore.xcframework

DatadogLogs.xcframework
DatadogTrace.xcframework
DatadogSessionReplay.xcframework
DatadogRUM.xcframework
DatadogCrashReporting.xcframework + CrashReporter.xcframework
DatadogWebViewTracking.xcframework
DatadogObjc.xcframework

Note: When using Crash Reporting and WebView Tracking, you must add the RUM and Logs modules to report events to RUM and Logs respectively.

Update @datadog/mobile-react-native in your package.json:

"@datadog/mobile-react-native": "2.0.0"

Update your iOS pods:

(cd ios && bundle exec pod update)

If you use a React Native version strictly over 0.67, use Java version 17. If you use React Native version equal or below ot 0.67, use Java version 11. To check your Java version, run the following in a terminal:

java --version

For React Native < 0.73

In your android/build.gradle file, specify the kotlinVersion to avoid clashes among Kotlin dependencies:

buildscript {
    ext {
        // targetSdkVersion = ...
        kotlinVersion = "1.8.21"
    }
}

For React Native < 0.68

In your android/build.gradle file, specify the kotlinVersion to avoid clashes among Kotlin dependencies:

buildscript {
    ext {
        // targetSdkVersion = ...
        kotlinVersion = "1.8.21"
    }
}

If you are using a version of com.android.tools.build:gradle below 5.0 in your android/build.gradle, add in your android/gradle.properties file:

android.jetifier.ignorelist=dd-sdk-android-core

Troubleshooting

Android build fails with Unable to make field private final java.lang.String java.io.File.path accessible

If your Android build fails with an error like:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:processReleaseMainManifest'.
> Unable to make field private final java.lang.String java.io.File.path accessible: module java.base does not "opens java.io" to unnamed module @1bbf7f0e

You are using Java 17, which is not compatible with your React Native version. Switch to Java 11 to solve the issue.

Android build fails with Unsupported class file major version 61

If your Android build fails with an error like:

FAILURE: Build failed with an exception.

* What went wrong:
Could not determine the dependencies of task ':app:lintVitalRelease'.
> Could not resolve all artifacts for configuration ':app:debugRuntimeClasspath'.
   > Failed to transform dd-sdk-android-core-2.0.0.aar (com.datadoghq:dd-sdk-android-core:2.0.0) to match attributes {artifactType=android-manifest, org.gradle.category=library, org.gradle.dependency.bundling=external, org.gradle.libraryelements=aar, org.gradle.status=release, org.gradle.usage=java-runtime}.
      > Execution failed for JetifyTransform: /Users/me/.gradle/caches/modules-2/files-2.1/com.datadoghq/dd-sdk-android-core/2.0.0/a97f8a1537da1de99a86adf32c307198b477971f/dd-sdk-android-core-2.0.0.aar.
         > Failed to transform '/Users/me/.gradle/caches/modules-2/files-2.1/com.datadoghq/dd-sdk-android-core/2.0.0/a97f8a1537da1de99a86adf32c307198b477971f/dd-sdk-android-core-2.0.0.aar' using Jetifier. Reason: IllegalArgumentException, message: Unsupported class file major version 61. (Run with --stacktrace for more details.)

You use a version of Android Gradle Plugin below 5.0. To fix the issue, add in your android/gradle.properties file:

android.jetifier.ignorelist=dd-sdk-android-core

Android build fails with Duplicate class kotlin.collections.jdk8.*

If your Android build fails with an error like:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:checkReleaseDuplicateClasses'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable
   > Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules jetified-kotlin-stdlib-1.8.10 (org.jetbrains.kotlin:kotlin-stdlib:1.8.10) and jetified-kotlin-stdlib-jdk8-1.7.20 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.20)
     Duplicate class kotlin.internal.jdk7.JDK7PlatformImplementations found in modules jetified-kotlin-stdlib-1.8.10 (org.jetbrains.kotlin:kotlin-stdlib:1.8.10) and jetified-kotlin-stdlib-jdk7-1.7.20 (org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.7.20)

You need to set a Kotlin version for your project to avoid clashes among Kotlin dependencies. In your android/build.gradle file, specify the kotlinVersion:

buildscript {
    ext {
        // targetSdkVersion = ...
        kotlinVersion = "1.8.21"
    }
}

Alternatively, you can add the following rules to your build script in your android/app/build.gradle file:

dependencies {
    constraints {
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.8.10") {
            because("kotlin-stdlib-jdk7 is now a part of kotlin-stdlib")
        }
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.10") {
            because("kotlin-stdlib-jdk8 is now a part of kotlin-stdlib")
        }
    }
}

Update datadog_flutter_plugin in your pubspec.yaml:

dependencies:
  'datadog_flutter_plugin: ^2.0.0

Troubleshooting

Duplicate interface (iOS)

If you see this error while building iOS after upgrading to datadog_flutter_plugin v2.0:

Semantic Issue (Xcode): Duplicate interface definition for class 'DatadogSdkPlugin'
/Users/exampleuser/Projects/test_app/build/ios/Debug-iphonesimulator/datadog_flutter_plugin/datadog_flutter_plugin.framework/Headers/DatadogSdkPlugin.h:6:0

Try performing flutter clean && flutter pub get and rebuilding. This usually resolves the issue.

Duplicate classes (Android)

If you see this error while building Android after the upgrading to datadog_flutter_plugin v2.0:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:checkDebugDuplicateClasses'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.CheckDuplicatesRunnable

Make sure that you’ve updated your version of Kotlin to at least 1.8 in your build.gradle file.

With the extraction of different products into independent modules, the SDK configuration is organized by module.

com.datadog.android.core.configuration.Configuration.Builder class has the following changes:

• Client token, env name, variant name (default value is empty string), and service name (default value is application ID taken from the manifest) should be provided in the constructor.
• The com.datadog.android.core.configuration.Credentials class is removed.
• logsEnabled, tracesEnabled, and rumEnabled are removed from the constructor in favour of individual product configuration (see below).
• crashReportsEnabled constructor argument is removed. You can enable or disable JVM crash reporting with the Configuration.Builder.setCrashReportsEnabled method. By default, JVM crash reporting is enabled.
• RUM, Logs, and Trace product configuration methods are removed from Configuration.Builder in favor of the individual product configuration (see below).

The Datadog.initialize method has the Credentials class removed from the list of the arguments.

The com.datadog.android.plugin package and all related classes/methods are removed.

Logs

All the classes related to the Logs product are strictly contained in the com.datadog.android.log package.

To use Logs product, import the following artifact:

implementation("com.datadoghq:dd-sdk-android-logs:x.x.x")

You can enable the Logs product with the following snippet:

val logsConfig = LogsConfiguration.Builder()
    ...
    .build()

Logs.enable(logsConfig)

val logger = Logger.Builder()
    ...
    .build()

API changes:

Trace

All the classes related to the Trace product are strictly contained in the com.datadog.android.trace package (this means that all classes residing in com.datadog.android.tracing before have moved).

To use the Trace product, import the following artifact:

implementation("com.datadoghq:dd-sdk-android-trace:x.x.x")

You can enable the Trace product with the following snippet:

val traceConfig = TraceConfiguration.Builder()
    ...
    .build()

Trace.enable(traceConfig)

val tracer = AndroidTracer.Builder()
    ...
    .build()

GlobalTracer.registerIfAbsent(tracer)

API changes:

RUM

All classes related to the RUM product are strictly contained in the com.datadog.android.rum package.

To use the RUM product, import the following artifact:

implementation("com.datadoghq:dd-sdk-android-rum:x.x.x")

You can enable the RUM product with the following snippet:

val rumConfig = RumConfiguration.Builder(rumApplicationId)
    ...
    .build()

Rum.enable(rumConfig)

API changes:

NDK Crash Reporting

The artifact name stays the same as before: com.datadoghq:dd-sdk-android-ndk:x.x.x.

You can enable NDK Crash Reporting with the following snippet:

NdkCrashReports.enable()

This configuration replaces the com.datadog.android.core.configuration.Configuration.Builder.addPlugin call.

Note: You should have RUM and Logs products enabled to receive NDK crash reports in RUM and Logs respectively.

WebView Tracking

The artifact name stays the same as before: com.datadoghq:dd-sdk-android-webview:x.x.x

You can enable WebView Tracking with the following snippet:

WebViewTracking.enable(webView, allowedHosts)

Note: You should have RUM and Logs products enabled to receive events coming from WebView in RUM and Logs respectively.

API changes:

OkHttp Tracking

To use OkHttp Tracking, import the following artifact:

implementation("com.datadoghq:dd-sdk-android-okhttp:x.x.x")

OkHttp instrumentation supports the initialization of the Datadog SDK after the OkHttp client, allowing you to create com.datadog.android.okhttp.DatadogEventListener, com.datadog.android.okhttp.DatadogInterceptor, and com.datadog.android.okhttp.trace.TracingInterceptor before the Datadog SDK. OkHttp instrumentation starts reporting events to Datadog once the Datadog SDK is initialized.

Both com.datadog.android.okhttp.DatadogInterceptor and com.datadog.android.okhttp.trace.TracingInterceptor allow you to control sampling dynamically through integration with a remote configuration system.

To dynamically adjust sampling, provide your own implementation of the com.datadog.android.core.sampling.Sampler interface in the com.datadog.android.okhttp.DatadogInterceptor/com.datadog.android.okhttp.trace.TracingInterceptor constructor. It is queried for each request to make the sampling decision.

dd-sdk-android-ktx module removal

To improve granularity for the Datadog SDK libraries used, the dd-sdk-android-ktx module is removed. The code is distributed between the other modules to provide extension methods for both RUM and Trace features.

Session Replay

For instructions on setting up Mobile Session Replay, see Mobile Session Replay Setup and Configuration.

With the extraction of different products into independent modules, the SDK configuration is organized by module.

The SDK must be initialized before enabling any product.

The Builder pattern of the SDK initialization has been removed in favor of structure definitions. The following example shows how a 1.x initialization would translate in 2.0.

V1 Initialization

import Datadog

Datadog.initialize(
    appContext: .init(),
    trackingConsent: .granted,
    configuration: Datadog.Configuration
        .builderUsing(
            clientToken: "<client token>",
            environment: "<environment>"
        )
        .set(serviceName: "<service name>")
        .build()

V2 Initialization

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        service: "<service name>"
    ),
    trackingConsent: .granted
)

API changes:

Logs

All the classes related to Logs are strictly in the DatadogLogs module. You first need to enable the product:

import DatadogLogs

Logs.enable(with: Logs.Configuration(...))

Then, you can create a logger instance:

import DatadogLogs

let logger = Logger.create(
    with: Logger.Configuration(name: "<logger name>")
)

API changes:

Trace

All the classes related to Trace are strictly in the DatadogTrace module. You first need to enable the product:

import DatadogTrace

Trace.enable(
    with: Trace.Configuration(...)
)

Then, you can access the shared Tracer instance:

import DatadogTrace

let tracer = Tracer.shared()

API changes:

RUM

All the classes related to RUM are strictly in the DatadogRUM module. You first need to enable the product:

import DatadogRUM

RUM.enable(
    with: RUM.Configuration(applicationID: "<RUM Application ID>")
)

Then, you can access the shared RUM monitor instance:

import DatadogRUM

let monitor = RUMMonitor.shared()

API changes:

Crash Reporting

To enable Crash Reporting, make sure to enable RUM and Logs to report to those products respectively.

import DatadogCrashReporting

CrashReporting.enable()

WebView Tracking

To enable WebViewTracking, make sure to also enable RUM and Logs to report to those products respectively.

import WebKit
import DatadogWebViewTracking

let webView = WKWebView(...)
WebViewTracking.enable(webView: webView)

Session Replay

For instructions on setting up Mobile Session Replay, see Mobile Session Replay Setup and Configuration.

No change in the SDK initialization is needed.

SDK Configuration Changes

Certain configuration properties have been moved or renamed to support modularity in Datadog’s native SDKs.

The following structures have been renamed:

The following properties have changed:

In addition, the following APIs have changed:

Flutter Web Changes

Clients using Flutter Web should update to using the Datadog Browser SDK v5. Change the following import in your index.html:

-  <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs-v4.js"></script>
-  <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-rum-slim-v4.js"></script>
+  <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/us1/v5/datadog-logs.js"></script>
+  <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js"></script>

Note: Datadog provides one CDN bundle per site. See the Browser SDK README for a list of all site URLs.

Logs product changes

As with v1, Datadog Logging can be enabled by setting the DatadogConfiguration.loggingConfiguration member. However, unlike v1, Datadog does not create a default logger for you. DatadogSdk.logs is now an instance of DatadogLogging, which can be used to create logs. Many options were moved to DatadogLoggerConfiguration to give developers more granular support over individual loggers.

The following APIs have changed:

RUM Product Changes

The following APIs have changed:

Additionally, event mappers no longer allow you to modify their view names. To rename a view, use a custom ViewInfoExtractor instead.