You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cab4b4f
Browse filesBrowse the repository at this point in the historyBrowse files
Document Navigation 3 support on the Android navigation integration page and clarify how it differs from the existing Navigation 2 integration. Align the examples with the current SDK API shape, including route name extraction, optional argument extraction, back stack capture options, and route data scrubbing.
Copy file name to clipboardExpand all lines: docs/platforms/android/integrations/navigation/index.mdx
+290-9Lines changed: 290 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,25 +3,43 @@ title: Navigation
3
3
caseStyle: camelCase
4
4
supportLevel: production
5
5
sdk: sentry.java.android.navigation
6
-
description: "Learn more about the Sentry Navigation integration for the Android SDK."
6
+
description: "Learn more about Sentry's navigation integrations for the Android SDK."
7
7
categories:
8
8
- mobile
9
9
---
10
10
11
-
The `sentry-android-navigation`library provides [AndroidX Navigation](https://developer.android.com/jetpack/androidx/releases/navigation) support for Sentry using the [SentryNavigationListener](https://github.com/getsentry/sentry-java/blob/524ee49b212c3f2eead20960c3c6825ccdbf8007/sentry-android-navigation/src/main/java/io/sentry/android/navigation/SentryNavigationListener.kt). The source can be found [on GitHub](https://github.com/getsentry/sentry-java/tree/main/sentry-android-navigation/src/main/java/io/sentry/android/navigation).
11
+
The `sentry-android-navigation`and `sentry-android-navigation3` libraries provide support for Sentry's Android navigation instrumentation. Use them to automatically add breadcrumbs, track screen names, and start navigation transactions whenever users navigate around your app.
12
12
13
-
On this page, we get you up and running with Sentry's Navigation Integration, so that it will automatically add a breadcrumb and start a transaction for each navigation event.
13
+
This page covers both:
14
14
15
-
## Install
15
+
-**Navigation 2** (`androidx.navigation`) via `SentryNavigationListener`
16
+
-**Navigation 3** (`androidx.navigation3`) via `SentryNavEffect`
17
+
18
+
If you're still using `NavController`, follow the Navigation 2 setup below. If you've moved to `NavDisplay`, skip to [Navigation 3](#navigation-3).
19
+
20
+
## Navigation 2
21
+
22
+
<Alert>
23
+
24
+
If you're using Navigation 2 with Jetpack Compose, see <PlatformLinkto="/configuration/integrations/jetpack-compose/#jetpack-compose-navigation">Jetpack Compose Navigation</PlatformLink> instead.
25
+
26
+
</Alert>
27
+
28
+
### Install
16
29
17
30
Sentry captures data by adding a `NavController.OnDestinationChangedListener`. To add the Navigation integration, install the [Android SDK](/platforms/android/), then add the `sentry-android-navigation` dependency using Gradle:
Configuration should happen in the respective lifecycle callbacks, once you retrieve your `NavController` instance:
27
45
@@ -72,9 +90,9 @@ protected void onPause() {
72
90
73
91
By default, the navigation transaction finishes automatically after it reaches the specified [idleTimeout](/platforms/android/configuration/options/#idleTimeout) and all of its child spans are finished. You can customize the timeout to your needs.
74
92
75
-
## Verify
93
+
###Verify
76
94
77
-
This snippet includes a sample `Fragment` with a couple of navigation events and captures an intentional message, so you can test that everything is working as soon as you set it up:
95
+
The snippet below includes a sample `Fragment` with a couple of navigation events and captures an intentional message, so you can test that everything is working as soon as you set it up:
78
96
79
97
```kotlin
80
98
importandroid.os.Bundle
@@ -121,7 +139,7 @@ class HomeFragment : Fragment() {
121
139
}
122
140
```
123
141
124
-
## Customize the Recorded Breadcrumb/Transaction
142
+
###Customize the Recorded Breadcrumb/Transaction
125
143
126
144
By default, the Navigation integration captures route arguments as additional data on breadcrumbs and transactions. In case the arguments contain any PII data, you can strip it out by way of `BeforeBreadcrumbCallback` and `EventProcessor` respectively. To do that, [manually initialize](/platforms/android/manual-setup/#configuration-via-sentryoptions) the SDK and add the following snippet:
Navigation 3 support is available in `sentry-android-navigation3``8.60.0` and later.
176
+
177
+
See the [Limitations](#limitations) section below for additional restrictions.
178
+
179
+
</Alert>
180
+
181
+
Android's [Navigation 3 library](https://developer.android.com/guide/navigation/navigation-3) expects apps to manage their own back stack and to push and pop entries in order to navigate. Apps pass their back stack to a `NavDisplay` and define corresponding composables. `NavDisplay` renders those composables to screen as the back stack entries change.
182
+
183
+
`SentryNavEffect` instruments the back stack passed to `NavDisplay`. By default, every time the top of the back stack changes, `SentryNavEffect` will:
184
+
185
+
- start a new navigation transaction (and finish any prior navigation transaction)
186
+
- emit a breadcrumb
187
+
- update the currently tracked screen name
188
+
- record the latest 10 entries from the back stack as event context
189
+
190
+
See [Customize Nav3 Options](#customize-nav3-options) to learn how to modify those defaults.
191
+
192
+
### Install
193
+
194
+
Install the Android SDK and add Sentry's Navigation 3 library:
// Place SentryNavEffect in the same composable as your NavDisplay and call the
227
+
// effect first. Provide a BackStackEntryMapper with the values you want to
228
+
// show up in Sentry. Be sure to omit PII and other sensitive info.
229
+
SentryNavEffect(
230
+
backStack = backStack,
231
+
backStackEntryMapper = { entry ->
232
+
when (entry) {
233
+
isHome->SentryBackStackEntry("Home")
234
+
isProductDetail->
235
+
SentryBackStackEntry("ProductDetail", mapOf("product_id" to entry.productId))
236
+
...
237
+
}
238
+
}
239
+
)
240
+
241
+
// Configure your NavDisplay like usual.
242
+
NavDisplay(
243
+
backStack = backStack,
244
+
...
245
+
)
246
+
}
247
+
```
248
+
249
+
**Note:** Be sure to call `SentryNavEffect` before `NavDisplay` so the effect's transaction-creating machinery can be set up before any spans are produced by the initial nav destination. Otherwise, initial destination spans may be lost or parented under the wrong transaction.
250
+
251
+
Provide a `BackStackEntryMapper` that maps each entry in your back stack to the name and optional arguments you want displayed in Sentry. Keep names stable and arguments lightweight and performant. Avoid using `::class.simpleName` or anything else that R8 will obfuscate.
252
+
253
+
<Alert>
254
+
255
+
Values returned from `BackStackEntryMapper` are **not** scrubbed by the Sentry SDK of PII or other potentially sensitive information before being sent to Sentry. Only return names and arguments known to be safe, or sanitize them yourself in your `BackStackEntryMapper`.
256
+
257
+
</Alert>
258
+
259
+
260
+
<Alert>
261
+
262
+
Multiple, simultaneously active `SentryNavEffect` instances writing to the same [Sentry scope](https://docs.sentry.io/platforms/android/enriching-events/scopes/) are ***not*** supported. Violating this restriction can result in duplicated or interleaved data and undefined transaction behavior.
263
+
264
+
</Alert>
265
+
266
+
### Customize Nav3 Options
267
+
268
+
Use `SentryNavOptions` to disable breadcrumbs or transactions, or to limit how much of the back stack Sentry stores with captured events.
If you want to turn screen names on or off, configure the main SDK options when you initialize the Sentry SDK:
287
+
288
+
```kotlin
289
+
importio.sentry.android.core.SentryAndroid
290
+
291
+
SentryAndroid.init(this) { options ->
292
+
options.isEnableScreenTracking =true
293
+
}
294
+
```
295
+
296
+
### Verify
297
+
298
+
The snippet below defines `Home` and `ProductDetail` routes and a composable for displaying them. It adds both routes to an in-memory back stack and captures a message from the `ProductDetail` destination so you can verify the navigation data the Sentry SDK emits.
299
+
300
+
The snippet assumes the default `SentryNavOptions`. Screen names additionally require screen tracking to be enabled.
Tap **Open product detail**, then **Send test message**. In Sentry, open the event for `Navigation 3 smoke test` and verify the following:
380
+
381
+
- In **Breadcrumbs**, look for a navigation breadcrumb whose destination is `ProductDetail`. It should include `product_id` under `to_arguments`.
382
+
383
+

384
+
385
+
- In **Contexts**, check the Navigation context for a back stack containing `/ProductDetail` followed by `/Home`, with `product_id` under `entry_arguments`. Also check the App context for View Names containing `/ProductDetail`.
386
+
387
+

388
+

389
+
390
+
- If tracing is enabled and the transaction is sampled, open the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/traces/) view after the [idle timeout](/platforms/android/configuration/options/#idleTimeout) and inspect the `ProductDetail` transaction. Emitted nav data should appear under **Attributes → Arguments**, **Contexts → Navigation**, and **Breadcrumbs**.
391
+
392
+

393
+
394
+
### Using kotlinx.serialization
395
+
396
+
If your Nav3 back stack uses `@Serializable` keys, you can use [Kotlin serialization](https://kotlinlang.org/docs/serialization.html) to produce stable entry names. For performance reasons, don't serialize keys in their entirety as `arguments` if they might be large, deeply nested, or contain PII or other sensitive information.
name =ProductDetail.serializer().descriptor.serialName,
418
+
arguments =mapOf("product_id" to entry.productId)
419
+
)
420
+
...
421
+
}
422
+
}
423
+
```
424
+
425
+
### Limitations
426
+
427
+
`SentryNavEffect` treats the top entry in your back stack as the current screen. That works well for most Nav3 setups, but it means that `SentryNavEffect` does ***not***:
428
+
429
+
- understand the concept of Nav3 [Scenes](https://developer.android.com/guide/navigation/navigation-3/scenes) or multi-pane layouts
430
+
- track multiple back stacks
431
+
- permit multiple, simultaneously active `SentryNavEffect` instances
432
+
- make special accommodations for [predictive back](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture) gestures (e.g., spans produced by predictively rendered composables may appear under the current destination's transaction)
0 commit comments