ref(android): Support Nav3 for multi-Activity applications (JAVA-274)

Introduce Nav3 support for multi-Activity applications by managing shared SentryNavEffect state so that multiple instances can overlap during Activity transitions without interfering with one another.

Basic approach was to replace the IScopes instance that BackStackObserver already talks to with a a smarter version that can toggle between the shared underlying scope and a per-instance staged version, depending on whether the observer is associated with the incoming our outgoing SentryNavEffect.

Doing so let's us keep modifications to SentryNavEffect, BackStackObserver, etc. to a minimum, and makes it easy to swap out our implementation in the future, should we eventually hide our IScopes API behind a LocalSentrySpan-esque system (or any of a number of other possibilities).

Author: 0xadam-brown

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Improvements
+
+- Support Navigation 3 integration for multi-Activity applications, where each Activity has its own `SentryNavEffect` ([#6229](https://github.com/getsentry/sentry-java/pull/6229))
+  - Each `LifecycleOwner` (e.g., an Activity or Fragment) can have its own `SentryNavEffect`, as long as the user can't interact with more than one of those owners at a time. Owners that stay visible beneath the one the user interacts with (e.g., beneath a dialog or translucent Activity) are supported
+  - Limitations: Does not support nested or side-by-side `NavDisplay` and `SentryNavEffect` pairs within the same `LifecycleOwner`, or `SentryNavEffect`s in multiple owners the user can interact with at the same time (e.g., two Activities in [multi-resume mode](https://developer.android.com/develop/ui/views/layout/support-multi-window-mode))
+
 ### Fixes
 
 - Measure Session Replay's 1h recording cap and its touch-move debounce on a monotonic clock, so a device time change no longer stops a healthy recording early, keeps a finished one alive, or suppresses gesture events ([#6090](https://github.com/getsentry/sentry-java/pull/6090))

gradle/libs.versions.toml

@@ -107,11 +107,13 @@ androidx-core-ktx = { module = "androidx.core:core-ktx", version = "1.7.0" }
 androidx-fragment-ktx = { module = "androidx.fragment:fragment-ktx", version = "1.3.5" }
 androidx-lifecycle-common-java8 = { module = "androidx.lifecycle:lifecycle-common-java8", version.ref = "androidxLifecycle" }
 androidx-lifecycle-process = { module = "androidx.lifecycle:lifecycle-process", version.ref = "androidxLifecycle" }
+androidx-lifecycle-runtime-compose = { module = "androidx.lifecycle:lifecycle-runtime-compose", version = "2.8.3" }
 androidx-navigation-runtime = { module = "androidx.navigation:navigation-runtime", version.ref = "androidxNavigation" }
 androidx-navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "androidxNavigation" }
 androidx-navigation-fragment = { module = "androidx.navigation:navigation-fragment-ktx", version.ref = "androidxNavigation" }
 androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" }
 androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" }
+androidx-viewpager2 = { module = "androidx.viewpager2:viewpager2", version = "1.1.0" }
 androidx-room-compiler = { module = "androidx.room:room-compiler", version.ref = "room2" }
 androidx-room-ktx = { module = "androidx.room:room-ktx", version.ref = "room2" }
 androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room2" }

sentry-android-navigation3/build.gradle.kts

@@ -62,6 +62,9 @@ dependencies {
   implementation(projects.sentry)
 
   compileOnly(libs.androidx.compose.runtime)
+  // Provides androidx.lifecycle.compose.LocalLifecycleOwner. Hosts get it at runtime through
+  // Compose UI 1.7+ and navigation3-ui, both of which depend on it.
+  compileOnly(libs.androidx.lifecycle.runtime.compose)
 
   testImplementation(libs.androidx.compose.ui.test.junit4)
   testImplementation(libs.androidx.test.core)

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackConverter.kt

@@ -395,7 +395,9 @@ internal data class NormalizedSentryBackStackEntry(
   val name: String,
   /** Sanitized [SentryBackStackEntry.arguments] (i.e., bounded in size and depth). */
   val arguments: Map<String, Any?> = emptyMap(),
-  /** The reason why the SDK dropped host-provided arguments. */
+  /**
+   * The reason why the SDK dropped host-provided arguments, or null if no arguments were dropped.
+   */
   val argumentDropReason: ArgumentDropReason? = null,
 ) {
 

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackObserver.kt

@@ -2,25 +2,27 @@ package io.sentry.compose.navigation3
 
 import io.sentry.Breadcrumb
 import io.sentry.Hint
-import io.sentry.IScope
-import io.sentry.IScopes
 import io.sentry.ITransaction
-import io.sentry.PropagationContext
 import io.sentry.SentryIntegrationPackageStorage
 import io.sentry.SentryLevel.DEBUG
 import io.sentry.SentryLevel.INFO
+import io.sentry.SentryOptions
 import io.sentry.SpanStatus
 import io.sentry.TransactionContext
 import io.sentry.TransactionOptions
 import io.sentry.compose.navigation3.BackStackConverter.RetentionPolicy
 import io.sentry.compose.navigation3.PreparedChange.BackStackHasNewTop
 import io.sentry.compose.navigation3.PreparedChange.BackStackHasSameTop
 import io.sentry.compose.navigation3.PreparedChange.BackStackIsEmpty
+import io.sentry.compose.navigation3.lifecycle.INavScope
+import io.sentry.compose.navigation3.lifecycle.INavScopes
 import io.sentry.protocol.App
 import io.sentry.protocol.TransactionNameSource
 import io.sentry.util.IntegrationUtils.addIntegrationToSdkVersion
 import java.lang.ref.WeakReference
 
+internal const val NAVIGATION_CONTEXT_KEY: String = "Navigation"
+
 private const val NAVIGATION_OP: String = "navigation"
 
 /**
@@ -46,11 +48,11 @@ private const val NAVIGATION_OP: String = "navigation"
  *
  * **Thread safety**
  *
- * This class is ***not*** thread-safe. Clients should serialize calls to [onBackStackChanged] and
- * [cleanup] (e.g., via invocation from an `*Effect` or another form of thread confinement).
+ * This class is ***not*** thread-safe. Clients should serialize calls to [onBackStackChanged]
+ * (e.g., via invocation from an `*Effect` or another form of thread confinement).
  */
 internal class BackStackObserver<T : Any>(
-  private val scopes: IScopes,
+  private val scopes: INavScopes,
   private val options: SentryNavOptions,
   entryMapper: ForwardingBackStackEntryMapper<T>,
 ) {
@@ -110,25 +112,6 @@ internal class BackStackObserver<T : Any>(
     scopes.configureScope { scope -> applyChange(scope, change) }
   }
 
-  internal fun cleanup() {
-    previousTop = null
-    previousTopNormalized = null
-
-    scopes.configureScope { scope ->
-      navTransaction.stop(scope)
-      navScreen.clear(scope)
-
-      if (options.captureBackStack) {
-        // This observer owns the nav context while it's in the composition, and cleanup removes
-        // it to avoid leaking stale back stack data after observation stops. If the host app
-        // replaces one observer with another, there may be a brief gap where events lack nav
-        // context. Apps should keep the observer at the nav root so cleanup only runs when the
-        // navigation session is ending, not during normal destination changes.
-        navContext.clear(scope)
-      }
-    }
-  }
-
   private fun prepareChange(backStack: List<T>): PreparedChange<T> {
     val topEntry = backStack.lastOrNull() ?: return BackStackIsEmpty
     val data = backStack.extractData()
@@ -140,7 +123,7 @@ internal class BackStackObserver<T : Any>(
     }
   }
 
-  private fun applyChange(scope: IScope, change: PreparedChange<T>) {
+  private fun applyChange(scope: INavScope, change: PreparedChange<T>) {
     when (change) {
       is BackStackIsEmpty -> handleEmptyBackStack(scope)
       is BackStackHasNewTop -> handleNewTop(scope, change.previousTop, change.backStack)
@@ -185,7 +168,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   private fun handleNewTop(
-    scope: IScope,
+    scope: INavScope,
     previousTop: NormalizedSentryBackStackEntry?,
     currentBackStack: BackStackData<T>,
   ) {
@@ -212,19 +195,18 @@ internal class BackStackObserver<T : Any>(
         )
         ?.let { transaction -> navContext.updateTransaction(transaction, scope, currentBackStack) }
     } else {
-      // Rotate the propagation context.
-      scope.withPropagationContext { scope.setPropagationContext(PropagationContext()) }
+      scope.rotatePropagationContext()
     }
 
     storeAsPreviousTop(currentBackStack.topEntry, currentBackStack.topEntryNormalized)
   }
 
-  private fun handleSameTop(scope: IScope, backStack: BackStackData<T>) {
+  private fun handleSameTop(scope: INavScope, backStack: BackStackData<T>) {
     navContext.update(scope, backStack.capturedEntriesNormalized)
     storeAsPreviousTop(backStack.topEntry, backStack.topEntryNormalized)
   }
 
-  private fun handleEmptyBackStack(scope: IScope) {
+  private fun handleEmptyBackStack(scope: INavScope) {
     navTransaction.stop(scope)
     navContext.clear(scope)
     navScreen.clear(scope)
@@ -245,7 +227,7 @@ internal class BackStackObserver<T : Any>(
 /**
  * A model for applying one back stack update.
  *
- * Lets us separate change preparation from its application so that the [IScopes.configureScope]
+ * Lets us separate change preparation from its application so that the [INavScopes.configureScope]
  * callback in charge of application can use already-computed navigation state. Otherwise, any
  * exceptions thrown during state computation would be swallowed by `configureScope`'s over-broad
  * `catch` clause.
@@ -281,7 +263,7 @@ private data class BackStackData<T>(
 )
 
 /** A helper class for managing nav transactions. */
-private class NavTransaction(private val scopes: IScopes) {
+private class NavTransaction(private val scopes: INavScopes) {
 
   private companion object {
     private const val TRANSACTION_ORIGIN = "auto.navigation.nav3"
@@ -291,11 +273,11 @@ private class NavTransaction(private val scopes: IScopes) {
 
   /** Starts an idle navigation transaction, or no-ops if another transaction is already active. */
   fun start(
-    scope: IScope,
+    scope: INavScope,
     name: String,
     arguments: Map<String, Any?>,
   ): ITransaction? {
-    clearTransactionIfFinished(scope)
+    scope.clearFinishedTransaction()
 
     if (scope.transaction != null) {
       scopes.options.logger.log(
@@ -335,61 +317,39 @@ private class NavTransaction(private val scopes: IScopes) {
       }
     }
 
-    scope.withTransaction { tx ->
-      if (tx == null) {
-        scope.transaction = transaction
-      }
-    }
+    scope.bindTransaction(transaction)
 
     return transaction
   }
 
   /** Finishes and unsets the active navigation transaction, if one exists. */
-  fun stop(scope: IScope) {
+  fun stop(scope: INavScope) {
     val transaction = activeNavTransaction ?: return
     val status = transaction.status ?: SpanStatus.OK
     transaction.finish(status)
-
-    scope.withTransaction { tx ->
-      if (tx == transaction) {
-        scope.clearTransaction()
-      }
-    }
-
+    scope.unbindTransaction(transaction)
     activeNavTransaction = null
   }
-
-  /** Clears a stale finished transaction that's still bound to the default scope. */
-  private fun clearTransactionIfFinished(scope: IScope) {
-    scope.withTransaction { tx ->
-      if (tx?.isFinished == true) {
-        scope.clearTransaction()
-      }
-    }
-  }
 }
 
 /** A helper class for updating [nav context][NAVIGATION_CONTEXT_KEY]. */
-private class NavContext(private val scopes: IScopes, private val options: SentryNavOptions) {
+private class NavContext(private val scopes: INavScopes, private val options: SentryNavOptions) {
 
   private companion object {
     private const val BACKSTACK_KEY = "Back Stack"
-    private const val NAVIGATION_CONTEXT_KEY = "Navigation"
   }
 
-  fun update(scope: IScope, backStackEntries: List<NormalizedSentryBackStackEntry>) {
+  fun update(scope: INavScope, backStackEntries: List<NormalizedSentryBackStackEntry>) {
     if (backStackEntries.isEmpty()) {
       clear(scope)
       return
     }
 
-    scope.setContexts(NAVIGATION_CONTEXT_KEY, backStackEntries.toBackStackMap())
+    scope.setNavigationContext(backStackEntries.toBackStackMap())
   }
 
-  fun clear(scope: IScope) {
-    // We purposefully don't call IScope.removeContexts(), as it doesn't notify IScopeObserver and
-    // therefore doesn't write its updates to disk ¯\_ (ツ)_/¯.
-    scope.setContexts(NAVIGATION_CONTEXT_KEY, null as Any?)
+  fun clear(scope: INavScope) {
+    scope.setNavigationContext(null)
   }
 
   /**
@@ -403,12 +363,11 @@ private class NavContext(private val scopes: IScopes, private val options: Sentr
    */
   fun <T : Any> updateTransaction(
     transaction: ITransaction,
-    scope: IScope,
+    scope: INavScope,
     backStack: BackStackData<T>,
   ) {
     if (scopes.options.isEnableScreenTracking) {
-      val appContext =
-        transaction.contexts.app ?: io.sentry.protocol.Contexts(scope.contexts).app ?: App()
+      val appContext = transaction.contexts.app ?: scope.app ?: App()
 
       appContext.viewNames = listOf(backStack.topEntryNormalized.name)
       transaction.contexts.setApp(appContext)
@@ -432,12 +391,12 @@ private class NavScreen {
 
   private var lastScreenName: String? = null
 
-  fun update(scope: IScope, currentEntry: NormalizedSentryBackStackEntry) {
+  fun update(scope: INavScope, currentEntry: NormalizedSentryBackStackEntry) {
     scope.screen = currentEntry.name
     lastScreenName = currentEntry.name
   }
 
-  fun clear(scope: IScope) {
+  fun clear(scope: INavScope) {
     val screenName = lastScreenName ?: return
     if (scope.screen == screenName) {
       scope.screen = null
@@ -447,7 +406,7 @@ private class NavScreen {
 }
 
 /** A helper class for generating nav breadcrumbs. */
-private class NavBreadcrumbs(private val scopes: IScopes) {
+private class NavBreadcrumbs(private val scopes: INavScopes) {
 
   fun emit(fromEntry: NormalizedSentryBackStackEntry?, toEntry: NormalizedSentryBackStackEntry) {
     val breadcrumb =