Skip to content

Commit 2b2f9bb

Browse files
ambushworkambushwork
committed
RUM-9755: Add Jetpack Compose Instrumentation documentation
1 parent aae22c7 commit 2b2f9bb

File tree

5 files changed

+240
-1
lines changed

5 files changed

+240
-1
lines changed

‎config/_default/menus/main.en.yaml

+6-1
Original file line numberDiff line numberDiff line change
@@ -7168,11 +7168,16 @@ menu:
71687168
parent: rum_mobile_android
71697169
identifier: rum_mobile_android_integrated_libraries
71707170
weight: 108
7171+
- name: Jetpack Compose Instrumentation
7172+
url: real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation
7173+
parent: rum_mobile_android
7174+
identifier: rum_mobile_android_jetpack_compose_instrumentation
7175+
weight: 109
71717176
- name: Troubleshooting
71727177
url: real_user_monitoring/mobile_and_tv_monitoring/android/troubleshooting
71737178
parent: rum_mobile_android
71747179
identifier: rum_mobile_android_troubleshooting
7175-
weight: 109
7180+
weight: 110
71767181
- name: iOS and tvOS
71777182
url: real_user_monitoring/mobile_and_tv_monitoring/ios
71787183
parent: mobile_and_tv_monitoring

‎content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md

+1
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,5 @@ To get started with RUM for Android, create an application and configure the And
3333
<u>Integrated Libraries</u>: Import integrated libraries for your Android and Android TV applications.{{< /nextlink >}}
3434
{{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/troubleshooting">}}
3535
<u>Troubleshooting</u>: Common troubleshooting Android SDK issues.{{< /nextlink >}}
36+
{{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation">}}<u>Jetpack Compose Instrumentation</u>: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin. {{< /nextlink >}}
3637
{{< /whatsnext >}}

‎content/en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+233
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
---
2+
title: Jetpack Compose Instrumentation
3+
description: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin.
4+
aliases:
5+
- /real_user_monitoring/android/jetpack_compose_instrumentation/
6+
- /real_user_monitoring/mobile_and_tv_monitoring/jetpack_compose_instrumentation/android
7+
further_reading:
8+
- link: https://github.com/DataDog/dd-sdk-android/tree/develop/integrations/dd-sdk-android-compose
9+
tag: "Source Code"
10+
text: Source code for dd-sdk-android-compose
11+
- link: https://github.com/DataDog/dd-sdk-android-gradle-plugin
12+
tag: "Source Code"
13+
text: Source code for Datadog Gradle Plugin
14+
- link: /real_user_monitoring
15+
tag: Documentation
16+
text: Explore Datadog RUM
17+
---
18+
## Overview
19+
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.
20+
21+
<div class="alert alert-info"><p>The minimum supported Kotlin version is 1.9.23.</p></div>
22+
23+
After initial setup, you can choose between [automatic](#automatic-instrumentation) and [manual](#manual-instrumentation) instrumentation.
24+
25+
## Setup
26+
### Step 1 - Declare "dd-sdk-android-compose" as a dependency
27+
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.
28+
The minimum version of `dd-sdk-android-compose` for Jetpack Compose instrumentation is 2.21.0.
29+
{{< tabs >}}
30+
{{% tab "Groovy" %}}
31+
```groovy
32+
dependencies {
33+
implementation "com.datadoghq:dd-sdk-android-compose:x.x.x"
34+
//(...)
35+
}
36+
```
37+
{{% /tab %}}
38+
{{% tab "Kotlin" %}}
39+
```kotlin
40+
dependencies {
41+
implementation("com.datadoghq:dd-sdk-android-compose:x.x.x")
42+
//(...)
43+
}
44+
```
45+
{{% /tab %}}
46+
{{< /tabs >}}
47+
48+
### Step 2 - Enable actions tracking option in `RumConfiguration`
49+
After adding the dependency, enable Compose action tracking in your `RumConfiguration`. This step is required regardless of the instrumentation mode.
50+
{{< tabs >}}
51+
{{% tab "Kotlin" %}}
52+
```kotlin
53+
val rumConfig = RumConfiguration.Builder(applicationId)
54+
//other configurations that you have already set
55+
.enableComposeActionTracking()
56+
.build()
57+
Rum.enable(rumConfig)
58+
```
59+
{{% /tab %}}
60+
{{% tab "Java" %}}
61+
```java
62+
RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
63+
//other configurations that you have already set
64+
.enableComposeActionTracking()
65+
.build();
66+
Rum.enable(rumConfig);
67+
```
68+
{{% /tab %}}
69+
{{< /tabs >}}
70+
71+
## Automatic Instrumentation
72+
73+
For full RUM coverage with minimal setup, you can automatically instrument your Jetpack Compose application.
74+
75+
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.
76+
77+
<div class="alert alert-info"><p>
78+
The Datadog Gradle Plugin scans <code>@Composable</code> 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 <code>NavHost</code> usage and listens to Jetpack Compose navigation events.
79+
</p></div>
80+
81+
### Step 1 - Declare Datadog Gradle Plugin in your buildscript
82+
The minimum version of Datadog Gradle Plugin for Jetpack Compose instrumentation is 1.17.0.
83+
{{< tabs >}}
84+
{{% tab "Groovy" %}}
85+
```groovy
86+
buildscript {
87+
dependencies {
88+
classpath "com.datadoghq:dd-sdk-android-gradle-plugin:x.x.x"
89+
}
90+
}
91+
92+
plugins {
93+
id 'com.datadoghq.dd-sdk-android-gradle-plugin'
94+
//(...)
95+
}
96+
```
97+
{{% /tab %}}
98+
{{% tab "Kotlin" %}}
99+
```kotlin
100+
buildscript {
101+
dependencies {
102+
classpath("com.datadoghq:dd-sdk-android-gradle-plugin:x.x.x")
103+
}
104+
}
105+
106+
plugins {
107+
id("com.datadoghq.dd-sdk-android-gradle-plugin")
108+
//(...)
109+
}
110+
```
111+
{{% /tab %}}
112+
{{< /tabs >}}
113+
114+
### Setup 2 - Select the instrumentation mode
115+
In your module's Gradle configuration, define the desired Compose instrumentation mode:
116+
117+
{{< tabs >}}
118+
{{% tab "Groovy" %}}
119+
```groovy
120+
datadog {
121+
// Other configurations that you may set before.
122+
//(...)
123+
124+
// Jetpack Compose instrumentation mode option.
125+
composeInstrumentation = InstrumentationMode.AUTO
126+
}
127+
```
128+
{{% /tab %}}
129+
{{% tab "Kotlin" %}}
130+
```kotlin
131+
datadog {
132+
// Other configurations that you may set before.
133+
//(...)
134+
135+
// Jetpack Compose instrumentation mode option.
136+
composeInstrumentation = InstrumentationMode.AUTO
137+
}
138+
```
139+
{{% /tab %}}
140+
{{< /tabs >}}
141+
142+
Available instrumentation modes:
143+
- `InstrumentationMode.AUTO`: Instruments all `@Composable` functions.
144+
- `InstrumentationMode.ANNOTATION`: Only instruments `@Composable` functions annotated with `@ComposeInstrumentation`. You can define the scope of auto-instrumentation by using this annotation.
145+
- `InstrumentationMode.DISABLE`: Disables instrumentation completely.
146+
147+
**Note**: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.
148+
149+
### How names are assigned with auto-instrumentation
150+
When auto-instrumentation is enabled:
151+
- The **Compose navigation route** is used as the **view name**.
152+
- The **name of the direct composable function** that wraps an interactive element is used as the **action target**.
153+
154+
```kotlin
155+
@Composable
156+
fun AppScaffold(){
157+
NavHost(navController = rememberNavController(), startDestination = "Home Screen"){
158+
composable("Home Screen"){
159+
HomeScreen()
160+
}
161+
}
162+
}
163+
164+
@Composable
165+
fun CustomButton(onClick: () -> Unit) {
166+
Button(onClick = onClick){
167+
Text("Welcome Button")
168+
}
169+
}
170+
```
171+
In the example above:
172+
- "Home Screen" is used as the **view name** when `HomeScreen()` is loaded.
173+
- "CustomButton" is used as the **action target** when the button is clicked.
174+
175+
{{< img src="real_user_monitoring/android/android-auto-instrumentation-naming.png" alt="Default naming of auto-instrumentation" style="width:90%;">}}
176+
177+
178+
## Manual Instrumentation
179+
180+
If you need more customization or control over actions and views tracking, you can manually instrument your application(s).
181+
182+
### Actions tracking
183+
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.
184+
```kotlin
185+
@Composable
186+
fun HomeScreen(){
187+
Column{
188+
Image(modifier = Modifier.datadog(name = "Welcome Image").clickable{
189+
// Action can be tracked if this image is clickable
190+
},
191+
// Other arguments
192+
)
193+
194+
Text(modifier = Modifier.datadog(name = "Welcome Text").clickable{
195+
// Action can be tracked if this text is clickable
196+
},
197+
// Other arguments
198+
)
199+
}
200+
}
201+
```
202+
In the example above, the custom names are used for the interactive elements in Rum actions tracking.
203+
204+
{{< img src="real_user_monitoring/android/android-actions-tracking-1.png" alt="Component name in actions tracking" style="width:90%;">}}
205+
206+
207+
### Views tracking
208+
To enable RUM view tracking based on Jetpack Compose navigation, call the `NavigationViewTrackingEffect` API and pass your app's `NavHostController`.
209+
```kotlin
210+
@Composable
211+
fun AppScaffold(){
212+
val navController = rememberNavController()
213+
NavigationViewTrackingEffect(
214+
navController = navController,
215+
trackArguments = true,
216+
destinationPredicate = AcceptAllNavDestinations()
217+
)
218+
NavHost(navController = navController,
219+
// other arguments
220+
) {
221+
// (...)
222+
}
223+
}
224+
```
225+
226+
## Further Reading
227+
228+
{{< partial name="whats-next/whats-next.html" >}}
229+
230+
[1]: https://github.com/DataDog/dd-sdk-android/tree/develop/integrations/dd-sdk-android-compose
231+
[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
232+
[3]: https://github.com/DataDog/dd-sdk-android-gradle-plugin
233+
[4]: https://developer.android.com/develop/ui/compose/accessibility/semantics

‎static/images/real_user_monitoring/android/android-actions-tracking-1.png

80.4 KB
Loading

‎static/images/real_user_monitoring/android/android-auto-instrumentation-naming.png

40 KB
Loading

0 commit comments

Comments
 (0)