Le passage de la version 1 à la version 2 correspond à une transition d’un SDK monolithique vers une architecture modulaire. Les SDK RUM, Trace, Logs ou encore Session Replay possèdent chacun des modules individuels vous permettant d’intégrer uniquement les éléments nécessaires dans votre application.

La version 2 du SDK harmonise la disposition de l’API ainsi que les différents noms entre le SDK iOS, le SDK Android et les autres solutions Datadog.

Avec la version 2 du SDK, vous pouvez utiliser [Session Replay sur mobile][1] dans les applications Android et iOS.

Le passage de la version 1 à la version 2 correspond à une transition d’un SDK monolithique vers une architecture modulaire. Les SDK RUM, Trace, Logs ou encore Session Replay possèdent chacun des modules individuels vous permettant d’intégrer uniquement les éléments nécessaires dans votre application.

La version 2 du SDK harmonise la disposition de l’API ainsi que les différents noms entre le SDK iOS, le SDK Android et les autres solutions Datadog.

Avec la version 2 du SDK, vous pouvez utiliser [Session Replay sur mobile][1] dans les applications Android et iOS.

La version 2 offre des performances supérieures par rapport à la version 1.

La version 2 offre des performances supérieures par rapport à la version 1. De plus, les SDK Native v2 proposent des fonctionnalités supplémentaires.

Dans la version 2, les artefacts sont modularisés. Adoptez les artefacts suivants :

• 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
• Suivi des vues Web : com.datadoghq:dd-sdk-android-webview:x.x.x
• Instrumentation OkHttp : com.datadoghq:dd-sdk-android-okhttp:x.x.x

Remarque : si vous utilisez les rapports de crash NDK et le suivi des vues Web, vous devez ajouter les artefacts RUM et Logs pour transmettre respectivement des événements à RUM et à la solution de logs.

La référence à l’artefact com.datadoghq:dd-sdk-android doit être supprimée du script du build Gradle, étant donné que cet artefact n’existe plus.

Remarque : les coordonnées Maven de tous les autres artefacts demeurent les mêmes.

Si jamais vous rencontrez une erreur semblable à ce qui suit :

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)

Ajoutez les règles suivantes au script de votre build (voir ce fil Stack Overflow pour obtenir plus d’informations) :

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")
        }
    }
}

Consultez l’extrait d’application Android pour obtenir un exemple de configuration du SDK.

Dans la version 2, les bibliothèques sont modularisées. Adoptez les bibliothèques suivantes :

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

Elles complètent les bibliothèques DatadogCrashReporting et DatadogObjc existantes.

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

Remarque : si vous utilisez les rapports de crash et le suivi des vues Web, vous devez ajouter les modules RUM et Logs pour transmettre respectivement des événements à RUM et à la solution de logs.

Mettez à jour @datadog/mobile-react-native dans votre package.json :

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

Mettez à jour vos pods iOS :

(cd ios && bundle exec pod update)

Si vous utilisez une version de React Native ultérieure à la version 0.67, utilisez la version 17 de Java. Si vous utilisez la version 0.67 ou une version antérieure de React Native, utilisez la version 11 de Java. Pour vérifier quelle version de Java vous utilisez, exécutez ce qui suit dans un terminal :

java --version

Pour les versions de React Native antérieures à la v0.73

Dans votre fichier android/build.gradle, spécifiez la kotlinVersion pour éviter les conflits entre les dépendances Kotlin :

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

Pour les versions de React Native antérieures à la v0.68

Dans votre fichier android/build.gradle, spécifiez la kotlinVersion pour éviter les conflits entre les dépendances Kotlin :

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

Si vous utilisez une version de com.android.tools.build:gradle antérieure à la version 5.0 dans votre android/build.gradle, ajoutez ce qui suit dans votre fichier android/gradle.properties :

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

Dépannage

Échec du build Android avec l’erreur Unable to make field private final java.lang.String java.io.File.path accessible

Si une erreur d’échec de votre build Android similaire à ce qui suit s’affiche :

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

Vous utilisez Java 17, qui n’est pas compatible avec votre version de React Native. Repassez à Java 11 pour résoudre le problème.

Échec du build Android avec l’erreur Unsupported class file major version 61

Si une erreur d’échec de votre build Android similaire à ce qui suit s’affiche :

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.)

Vous utilisez une version d’Android Gradle Plugin antérieure à la 5.0. Pour résoudre le problème, ajoutez ce qui suit à votre fichier android/gradle.properties :

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

Échec du build Android avec l’erreur Duplicate class kotlin.collections.jdk8.*

Si une erreur d’échec de votre build Android similaire à ce qui suit s’affiche :

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)

Vous devez définir une version Kotlin pour votre projet afin d’éviter les conflits entre les dépendances Kotlin. Dans votre fichier android/build.gradle, spécifiez la kotlinVersion :

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

Sinon, vous pouvez ajouter les règles suivantes au script de votre build dans votre fichier android/app/build.gradle :

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")
        }
    }
}

Mettez à jour datadog_flutter_plugin dans votre fichier pubspec.yaml :

dependencies:
  'datadog_flutter_plugin: ^2.0.0

Dépannage

Double interface (iOS)

Si, après avoir installé la version 2.0 de datadog_flutter_plugin, vous rencontrez l’erreur suivante lors du build iOS :

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

Essayez d’exécuter flutter clean && flutter pub get, puis relancez l’étape de build. Cela devrait résoudre le problème.

Double classe (Android)

Si, après avoir installé la version 2.0 de datadog_flutter_plugin, vous rencontrez l’erreur suivante lors du build Android :

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

Vérifiez que vous utilisez au minimum la version 1.8 de Kotlin dans votre fichier build.gradle.

Compte tenu de l’extraction de différentes solutions dans des modules indépendants, la configuration du SDK est organisée par module.

La classe com.datadog.android.core.configuration.Configuration.Builder présente les modifications suivantes :

• Le token client, le nom de l’environnement, le nom de la variante (la valeur par défaut est une chaîne vide) et le nom du service (la valeur par défaut est l’ID de l’application extrait du manifeste) doivent être fournis par le constructeur.
• La classe com.datadog.android.core.configuration.Credentials a été supprimée.
• logsEnabled, tracesEnabled et rumEnabled sont supprimés du constructeur au profit de la configuration individuelle des solutions (voir ci-dessous).
• L’argument de constructeur crashReportsEnabled a été supprimé. Vous pouvez activer ou désactiver les rapports de crash JVM à l’aide de la méthode Configuration.Builder.setCrashReportsEnabled. Par défaut, les rapports de crash JVM sont activés.
• Les méthodes de configuration des solutions RUM, de logs et de tracing sont supprimées de Configuration.Builder au profit d’une configuration individuelle des solutions (voir ci-dessous).

La classe Credentials a été supprimée de la liste d’arguments de la méthode Datadog.initialize.

Le package com.datadog.android.plugin et toutes les classes/méthodes qui lui sont associées sont supprimés.

Logs

Toutes les classes associées à la solution de logs sont contenues exclusivement dans le package com.datadog.android.log.

Pour utiliser la fonctionnalité de logs, importez l’artefact suivant :

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

Vous pouvez activer la solution de logs avec l’extrait de code suivant :

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

Logs.enable(logsConfig)

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

Modifications de l’API :

Trace

Toutes les classes associées à la solution de tracing sont contenues exclusivement dans le package com.datadog.android.trace (ce qui signifie que toutes les classes précédemment situées dans com.datadog.android.tracing ont été déplacées).

Pour utiliser la solution de tracing, importez l’artefact suivant :

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

Vous pouvez activer la solution de tracing avec l’extrait de code suivant :

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

Trace.enable(traceConfig)

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

GlobalTracer.registerIfAbsent(tracer)

Modifications de l’API :

RUM

Toutes les classes associées à la solution RUM sont contenues exclusivement dans le package com.datadog.android.rum.

Pour utiliser la solution RUM, importez l’artefact suivant :

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

Vous pouvez utiliser l’extrait de code suivant pour activer la solution RUM :

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

Rum.enable(rumConfig)

Modifications de l’API :

Rapports de crash NDK

Le nom de l’artefact reste le même qu’avant : com.datadoghq:dd-sdk-android-ndk:x.x.x.

Vous pouvez activer les rapports de crash NDK avec l’extrait de code suivant :

NdkCrashReports.enable()

Cette configuration remplace l’appel com.datadog.android.core.configuration.Configuration.Builder.addPlugin.

Remarque : vous devez avoir activé la solution RUM et la solution de logs afin de recevoir des rapports de crash NDK dans les interfaces RUM et Logs respectivement.

Suivi des vues Web

Le nom de l’artefact reste le même qu’avant : com.datadoghq:dd-sdk-android-webview:x.x.x.

Vous pouvez activer le suivi des vues Web avec l’extrait de code suivant :

WebViewTracking.enable(webView, allowedHosts)

Remarque : vous devez avoir activé la solution RUM et la solution de logs afin de recevoir les événements provenant des vues Web dans les interfaces RUM et Logs respectivement.

Modifications de l’API :

Suivi OkHttp

Pour utiliser le suivi OkHttp, importez l’artefact suivant :

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

L’instrumentation OkHttp prend en charge l’initialisation du SDK Datadog après le client OkHttp, ce qui vous permet de créer com.datadog.android.okhttp.DatadogEventListener, com.datadog.android.okhttp.DatadogInterceptor et com.datadog.android.okhttp.trace.TracingInterceptor avant le SDK Datadog. L’instrumentation OkHttp commence à transmettre des événements à Datadog après l’initialisation du SDK Datadog.

com.datadog.android.okhttp.DatadogInterceptor et com.datadog.android.okhttp.trace.TracingInterceptor vous permettent de contrôler l’échantillonnage de manière dynamique par le biais de l’intégration à un système de configuration à distance.

Pour ajuster l’échantillonnage de manière dynamique, fournissez votre propre implémentation de l’interface com.datadog.android.core.sampling.Sampler dans le constructeur com.datadog.android.okhttp.DatadogInterceptor/com.datadog.android.okhttp.trace.TracingInterceptor. Celle-ci est interrogée pour chaque requête afin de choisir ou non de procéder à un échantillonnage.

Suppression du module dd-sdk-android-ktx

Pour améliorer la granularité des bibliothèques du SDK Datadog utilisées, le module dd-sdk-android-ktx a été supprimé. Le code est distribué entre les autres modules afin de fournir des méthodes d’extension pour les fonctionnalités RUM et de tracing.

Session Replay

Pour découvrir comment configurer Session Replay sur mobile, consultez la section Installation et configuration de Session Replay sur mobile.

Compte tenu de l’extraction de différentes solutions dans des modules indépendants, la configuration du SDK est organisée par module.

Le SDK doit être initialisé avant d’activer toute solution.

Le pattern Builder de l’initialisation du SDK a été supprimé au profit de définitions de structure. L’exemple suivant illustre les différences d’initialisation entre la version 1.x et la version 2.0.

Initialisation (v1)

import Datadog

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

Initialisation (v2)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<token client>",
        env: "<environnement>",
        service: "<nom du service>"
    ),
    trackingConsent: .granted
)

Modifications de l’API :

Logs

Toutes les classes associées à la solution de logs sont contenues exclusivement dans le module DatadogLogs. Vous devez d’abord activer la solution :

import DatadogLogs

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

Vous pouvez ensuite créer votre instance de logger :

import DatadogLogs

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

Modifications de l’API :

Trace

Toutes les classes associées à la solution de tracing sont contenues exclusivement dans le module DatadogTrace. Vous devez d’abord activer la solution :

import DatadogTrace

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

Vous pouvez ensuite accéder à l’instance Tracer partagée :

import DatadogTrace

let tracer = Tracer.shared()

Modifications de l’API :

RUM

Toutes les classes associées à la solution RUM sont contenues exclusivement dans le module DatadogRUM. Vous devez d’abord activer la solution :

import DatadogRUM

RUM.enable(
    with: RUM.Configuration(applicationID: "<ID d'application RUM>")
)

Vous pouvez ensuite accéder à l’instance de monitor RUM partagée :

import DatadogRUM

let monitor = RUMMonitor.shared()

Modifications de l’API :

Rapports de crash

Pour activer les rapports de crash, veillez à activer la transmission des rapports aux solutions RUM et de logs respectivement.

import DatadogCrashReporting

CrashReporting.enable()

Suivi des vues Web

Pour activer le suivi des vues Web, veillez à activer également la transmission des rapports aux solutions RUM et de logs respectivement.

import WebKit
import DatadogWebViewTracking

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

Session Replay

Pour découvrir comment configurer Session Replay sur mobile, consultez la section Installation et configuration de Session Replay sur mobile.

Aucune modification ne doit être apportée à l’initialisation du SDK.

Modifications de configuration des SDK

Certaines propriétés de configuration ont été déplacées ou renommées, afin de prendre en charge la modularité dans les SDK natifs de Datadog.

Les structures suivantes ont été renommées :

Les propriétés suivantes ont été modifiées :

De plus, les API suivantes ont été modifiées :

Modifications apportées à Flutter Web

Les clients reposant sur Flutter Web doivent mettre à jour leur configuration afin d’utiliser la version 5 du SDK Browser Datadog. Modifiez l’importation suivante dans votre fichier 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>

Remarque : Datadog fournit un lot CDN par site. Consultez le fichier README du SDK Browser pour obtenir la liste de toutes les URL de site.

Modifications apportées à la fonctionnalité de logs

Comme pour la v1, la journalisation Datadog peut être activée à l’aide du membre DatadogConfiguration.loggingConfiguration. Toutefois, Datadog ne crée plus le logger à votre place. DatadogSdk.logs est désormais une instance de DatadogLogging. Vous pouvez vous en servir pour créer vos logs. Un grand nombre d’options ont été déplacées vers DatadogLoggerConfiguration, afin que les développeurs puissent contrôler plus précisément chaque logger.

Les API suivantes ont été modifiées :

Modifications apportées à la solution RUM

Les API suivantes ont été modifiées :

De plus, il n’est plus possible de modifier le nom des vues des mappers d’événements. Pour renommer une vue, utilisez plutôt un ViewInfoExtractor personnalisé.