diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index 2e79bda9a8bb6..f97826a9d87af 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -7168,11 +7168,16 @@ menu: parent: rum_mobile_android identifier: rum_mobile_android_integrated_libraries weight: 108 + - name: Jetpack Compose Instrumentation + url: real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation + parent: rum_mobile_android + identifier: rum_mobile_android_jetpack_compose_instrumentation + weight: 109 - name: Troubleshooting url: real_user_monitoring/mobile_and_tv_monitoring/android/troubleshooting parent: rum_mobile_android identifier: rum_mobile_android_troubleshooting - weight: 109 + weight: 110 - name: iOS and tvOS url: real_user_monitoring/mobile_and_tv_monitoring/ios parent: mobile_and_tv_monitoring diff --git a/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md b/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md index 5208b35bcf8b4..0b59ab710a07b 100644 --- a/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md +++ b/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md @@ -33,4 +33,5 @@ To get started with RUM for Android, create an application and configure the And Integrated Libraries: Import integrated libraries for your Android and Android TV applications.{{< /nextlink >}} {{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/troubleshooting">}} Troubleshooting: Common troubleshooting Android SDK issues.{{< /nextlink >}} + {{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation">}}Jetpack Compose Instrumentation: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin. {{< /nextlink >}} {{< /whatsnext >}} diff --git a/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md b/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md new file mode 100644 index 0000000000000..e48455bafb255 --- /dev/null +++ b/content/en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md @@ -0,0 +1,233 @@ +--- +title: Jetpack Compose Instrumentation +description: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin. +aliases: + - /real_user_monitoring/android/jetpack_compose_instrumentation/ + - /real_user_monitoring/mobile_and_tv_monitoring/jetpack_compose_instrumentation/android +further_reading: +- link: https://github.com/DataDog/dd-sdk-android/tree/develop/integrations/dd-sdk-android-compose + tag: "Source Code" + text: Source code for dd-sdk-android-compose +- link: https://github.com/DataDog/dd-sdk-android-gradle-plugin + tag: "Source Code" + text: Source code for Datadog Gradle Plugin +- link: /real_user_monitoring + tag: Documentation + text: Explore Datadog RUM +--- +## Overview +Jetpack Compose is a toolkit for building native UI in Android. If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views. + +

The minimum supported Kotlin version is 1.9.23.

+ +After initial setup, you can choose between [automatic](#automatic-instrumentation) and [manual](#manual-instrumentation) instrumentation. + +## Setup +### Step 1 - Declare "dd-sdk-android-compose" as a dependency +Add `dd-sdk-android-compose` as a dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose. +The minimum version of `dd-sdk-android-compose` for Jetpack Compose instrumentation is 2.21.0. +{{< tabs >}} +{{% tab "Groovy" %}} +```groovy +dependencies { + implementation "com.datadoghq:dd-sdk-android-compose:x.x.x" + //(...) +} +``` +{{% /tab %}} +{{% tab "Kotlin" %}} +```kotlin +dependencies { + implementation("com.datadoghq:dd-sdk-android-compose:x.x.x") + //(...) +} +``` +{{% /tab %}} +{{< /tabs >}} + +### Step 2 - Enable actions tracking option in `RumConfiguration` +After adding the dependency, enable Compose action tracking in your `RumConfiguration`. This step is required regardless of the instrumentation mode. +{{< tabs >}} +{{% tab "Kotlin" %}} +```kotlin +val rumConfig = RumConfiguration.Builder(applicationId) + //other configurations that you have already set + .enableComposeActionTracking() + .build() +Rum.enable(rumConfig) +``` +{{% /tab %}} +{{% tab "Java" %}} +```java +RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId) + //other configurations that you have already set + .enableComposeActionTracking() + .build(); +Rum.enable(rumConfig); +``` +{{% /tab %}} +{{< /tabs >}} + +## Automatic Instrumentation + +For full RUM coverage with minimal setup, you can automatically instrument your Jetpack Compose application. + +As described in Step 1 of the [Android setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument. + +

+The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events. +

+ +### Step 1 - Declare Datadog Gradle Plugin in your buildscript +The minimum version of Datadog Gradle Plugin for Jetpack Compose instrumentation is 1.17.0. +{{< tabs >}} +{{% tab "Groovy" %}} +```groovy +buildscript { + dependencies { + classpath "com.datadoghq:dd-sdk-android-gradle-plugin:x.x.x" + } +} + +plugins { + id 'com.datadoghq.dd-sdk-android-gradle-plugin' + //(...) +} +``` +{{% /tab %}} +{{% tab "Kotlin" %}} +```kotlin +buildscript { + dependencies { + classpath("com.datadoghq:dd-sdk-android-gradle-plugin:x.x.x") + } +} + +plugins { + id("com.datadoghq.dd-sdk-android-gradle-plugin") + //(...) +} +``` +{{% /tab %}} +{{< /tabs >}} + +### Setup 2 - Select the instrumentation mode +In your module's Gradle configuration, define the desired Compose instrumentation mode: + +{{< tabs >}} +{{% tab "Groovy" %}} +```groovy +datadog { + // Other configurations that you may set before. + //(...) + + // Jetpack Compose instrumentation mode option. + composeInstrumentation = InstrumentationMode.AUTO +} +``` +{{% /tab %}} +{{% tab "Kotlin" %}} +```kotlin +datadog { + // Other configurations that you may set before. + //(...) + + // Jetpack Compose instrumentation mode option. + composeInstrumentation = InstrumentationMode.AUTO +} +``` +{{% /tab %}} +{{< /tabs >}} + +Available instrumentation modes: +- `InstrumentationMode.AUTO`: Instruments all `@Composable` functions. +- `InstrumentationMode.ANNOTATION`: Only instruments `@Composable` functions annotated with `@ComposeInstrumentation`. You can define the scope of auto-instrumentation by using this annotation. +- `InstrumentationMode.DISABLE`: Disables instrumentation completely. + +**Note**: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default. + +### How names are assigned with auto-instrumentation +When auto-instrumentation is enabled: +- The **Compose navigation route** is used as the **view name**. +- The **name of the direct composable function** that wraps an interactive element is used as the **action target**. + +```kotlin +@Composable +fun AppScaffold(){ + NavHost(navController = rememberNavController(), startDestination = "Home Screen"){ + composable("Home Screen"){ + HomeScreen() + } + } +} + +@Composable +fun CustomButton(onClick: () -> Unit) { + Button(onClick = onClick){ + Text("Welcome Button") + } +} +``` +In the example above: +- "Home Screen" is used as the **view name** when `HomeScreen()` is loaded. +- "CustomButton" is used as the **action target** when the button is clicked. + +{{< img src="real_user_monitoring/android/android-auto-instrumentation-naming.png" alt="Default naming of auto-instrumentation" style="width:90%;">}} + + +## Manual Instrumentation + +If you need more customization or control over actions and views tracking, you can manually instrument your application(s). + +### Actions tracking +To track user interactions with specific Jetpack Compose components, apply the `datadog` modifier. The `name` argument defines the view name displayed in the RUM event list. +```kotlin +@Composable +fun HomeScreen(){ + Column{ + Image(modifier = Modifier.datadog(name = "Welcome Image").clickable{ + // Action can be tracked if this image is clickable + }, + // Other arguments + ) + + Text(modifier = Modifier.datadog(name = "Welcome Text").clickable{ + // Action can be tracked if this text is clickable + }, + // Other arguments + ) + } +} +``` +In the example above, the custom names are used for the interactive elements in Rum actions tracking. + +{{< img src="real_user_monitoring/android/android-actions-tracking-1.png" alt="Component name in actions tracking" style="width:90%;">}} + + +### Views tracking +To enable RUM view tracking based on Jetpack Compose navigation, call the `NavigationViewTrackingEffect` API and pass your app's `NavHostController`. +```kotlin +@Composable +fun AppScaffold(){ + val navController = rememberNavController() + NavigationViewTrackingEffect( + navController = navController, + trackArguments = true, + destinationPredicate = AcceptAllNavDestinations() + ) + NavHost(navController = navController, + // other arguments + ) { + // (...) + } +} +``` + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://github.com/DataDog/dd-sdk-android/tree/develop/integrations/dd-sdk-android-compose +[2]: https://docs.datadoghq.com/real_user_monitoring/mobile_and_tv_monitoring/android/setup?tab=rum#step-1---declare-the-android-sdk-as-a-dependency +[3]: https://github.com/DataDog/dd-sdk-android-gradle-plugin +[4]: https://developer.android.com/develop/ui/compose/accessibility/semantics diff --git a/static/images/real_user_monitoring/android/android-actions-tracking-1.png b/static/images/real_user_monitoring/android/android-actions-tracking-1.png new file mode 100644 index 0000000000000..a9ddf39ee1ec4 Binary files /dev/null and b/static/images/real_user_monitoring/android/android-actions-tracking-1.png differ diff --git a/static/images/real_user_monitoring/android/android-auto-instrumentation-naming.png b/static/images/real_user_monitoring/android/android-auto-instrumentation-naming.png new file mode 100644 index 0000000000000..f530d01723daa Binary files /dev/null and b/static/images/real_user_monitoring/android/android-auto-instrumentation-naming.png differ