fix(android): Nav3 support for ViewPager2 (JAVA-785) (#6398)

Make the multi-Activity and multi-Fragment support introduced by the #6301 PR stack play nicely with ViewPager2.

BACKGROUND

The approach in #6301 was smart about staging nav data (ie, screen name + nav context), but it didn't do the same for nav transactions. A new nav transaction could be started only if the lease was owned at the time of navigation, where "navigation" == initialization or modification of the nav back stack. Because the lease had to be owned, that meant that the Activity or Fragment hosting the SentryNavEffect requesting the lease had to be in a resumed state.

That^^ assumption made sense for most use cases, because usually initialization of an Activity or Fragment's nav back stack coincides with the Activity or Fragment being visible and therefore being able to preempt the lease from the previous leaseholder. But the assumption didn't pan out for ViewPager2, because ViewPager2 preloads neighboring pages. That means it initializes the nav back stack for Fragments that aren't in a resumed state and therefore can't preempt the lease, causing them to drop their initial nav transaction and any spans created by the initial destination screen. Sigh.

THE SOLUTION

The solution this commit implements is to create a mechanism similar to the data staging from #6301, but for transactions. Doing so lets us separate back stack initialization observed during preloading vs attempted lease acquisition when a ViewPager2 page becomes visible.

In particular, the new StagedNavTransaction class tracks requests to start nav transactions when a SentryNavEffect is created even if it doesn't currently have the lease. If the lease is later acquired and the transaction slot is available on the shared IScope, the staged transaction is started, which keeps ViewPager2 happy.

REFACTORING INCLUDED

Included in this commit is a refactor of code in the .navigation3.lifecycle package. The refactor lets us separate three responsibilities:

- Lease coordination: NavLeaseCoordinator observes registered owners’ lifecycles and decides which SentryNavEffect may publish navigation state.

- State publication: Each effect’s NavScopes publishes and withdraws its navigation data and transaction together when ownership changes.

- Transaction management: Each effect gets a transaction handle that manages starting, finishing, binding, and restoring its transaction. The coordinator no longer retains transactions itself.

Author: 0xadam-brown

CHANGELOG.md

@@ -16,6 +16,7 @@
 
 ### Fixes
 
+- Fix missing Navigation 3 transactions for preloaded ViewPager2 pages and destinations reached while another Activity or Fragment owns navigation tracking ([#6400](https://github.com/getsentry/sentry-java/pull/6400))
 - Keep UI profiling running when `startProfiler` is called before a requested stop takes effect at the end of the current chunk ([#6291](https://github.com/getsentry/sentry-java/pull/6291))
   - Before, the start call was ignored and the profiler still stopped at the end of the chunk, even in `TRACE` mode while sampled spans were active. On API 34 and lower, every later profile also stopped after one chunk.
 - Refuse to send data to servers whose certificate was issued by one of the leaked eMudhra intermediates (CVE-2026-111943) ([#6336](https://github.com/getsentry/sentry-java/pull/6336))

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

@@ -450,7 +450,7 @@ internal data class NormalizedSentryBackStackEntry(
 internal fun List<NormalizedSentryBackStackEntry>.serialize(): List<Map<String, Any?>> =
   map(NormalizedSentryBackStackEntry::serialize)
 
-/** Why host-provided arguments were unavailable in emitted navigation data. */
+/** Why host-provided arguments were unavailable in emitted nav state. */
 internal enum class ArgumentDropReason(
   val serializedValue: String,
   val exhaustsUpdateBudget: Boolean = false,

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

@@ -78,7 +78,7 @@ public class SentryBackStackEntry(
  *
  * If [map] throws, returns `null`, or returns a blank [name][SentryBackStackEntry.name], Sentry
  * records the destination as "/unknown". Doing so signals that name extraction needs to be fixed
- * while avoiding misleading gaps in navigation data.
+ * while avoiding misleading gaps in nav state.
  *
  * For instance, if a user navigates from `/home -> /detail -> /settings`, but the mapper for
  * `/detail` throws, the back stack record will be `/home -> /unknown -> /settings` rather than

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

@@ -2,12 +2,9 @@ package io.sentry.compose.navigation3
 
 import io.sentry.Breadcrumb
 import io.sentry.Hint
-import io.sentry.ITransaction
 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
@@ -16,6 +13,7 @@ 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.compose.navigation3.lifecycle.INavTransaction
 import io.sentry.compose.navigation3.lifecycle.NAVIGATION_CONTEXT_KEY
 import io.sentry.protocol.App
 import io.sentry.protocol.TransactionNameSource
@@ -59,7 +57,7 @@ internal class BackStackObserver<T : Any>(
 
   private val backStackConverter = BackStackConverter(entryMapper, scopes.options.logger)
 
-  private val navTransaction = NavTransaction(scopes)
+  private val navTransactions = NavTransactions(scopes)
   private val navBreadcrumbs = NavBreadcrumbs(scopes)
   private val navScreen = NavScreen()
   private val navContext = NavContext(scopes, options)
@@ -83,7 +81,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   /**
-   * Updates Sentry nav data based on the provided [backStack].
+   * Updates Sentry nav state based on the provided [backStack].
    *
    * **Data generated**
    *
@@ -113,7 +111,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   /**
-   * Clears the nav data this observer recorded.
+   * Clears the nav state this observer recorded.
    *
    * Call it when observation ends so that no stale screen, nav context, or nav transaction outlives
    * it.
@@ -194,10 +192,10 @@ internal class BackStackObserver<T : Any>(
       navBreadcrumbs.emit(fromEntry = previousTop, toEntry = currentBackStack.topEntryNormalized)
     }
 
-    navTransaction.stop(scope)
+    navTransactions.stop(scope)
 
     if (areNavigationTransactionsEnabled) {
-      navTransaction
+      navTransactions
         .start(
           scope,
           currentTop.name,
@@ -231,7 +229,7 @@ internal class BackStackObserver<T : Any>(
   }
 
   private fun tearDown(scope: INavScope) {
-    navTransaction.stop(scope)
+    navTransactions.stop(scope)
     navContext.clear(scope)
     navScreen.clear(scope)
     clearPreviousTop()
@@ -277,32 +275,22 @@ private data class BackStackData<T>(
 )
 
 /** A helper class for managing nav transactions. */
-private class NavTransaction(private val scopes: INavScopes) {
+private class NavTransactions(private val scopes: INavScopes) {
 
   private companion object {
     private const val TRANSACTION_ORIGIN = "auto.navigation.nav3"
   }
 
-  private var activeNavTransaction: ITransaction? = null
-
-  /** Starts an idle navigation transaction, or no-ops if another transaction is already active. */
+  /**
+   * Starts an idle navigation transaction, or no-ops if another transaction is already active.
+   *
+   * [Stop][stop] the current navigation transaction first. See [INavScope.startNavTransaction].
+   */
   fun start(
     scope: INavScope,
     name: String,
     arguments: Map<String, Any?>,
-  ): ITransaction? {
-    scope.clearFinishedTransaction()
-
-    if (scope.transaction != null) {
-      scopes.options.logger.log(
-        DEBUG,
-        "Nav3 transaction for route %s won't be created because another transaction is active.",
-        name,
-      )
-
-      return null
-    }
-
+  ): INavTransaction? {
     val transactionOptions =
       TransactionOptions().also {
         it.isWaitForChildren = true
@@ -314,36 +302,25 @@ private class NavTransaction(private val scopes: INavScopes) {
       }
 
     val transaction =
-      scopes.startTransaction(
+      scope.startNavTransaction(
         TransactionContext(name, TransactionNameSource.ROUTE, NAVIGATION_OP),
         transactionOptions,
-      )
+      ) ?: return null
 
-    // Not an error: INavScopes.startTransaction may decline to start a transaction by design.
-    if (transaction.isNoOp) {
-      return null
+    if (arguments.isNotEmpty()) {
+      transaction.setData("arguments", arguments)
     }
 
-    activeNavTransaction = transaction
-
-    transaction.apply {
-      if (arguments.isNotEmpty()) {
-        setData("arguments", arguments)
-      }
-    }
-
-    scope.bindTransaction(transaction)
-
     return transaction
   }
 
-  /** Finishes and unsets the active navigation transaction, if one exists. */
+  /**
+   * Finishes and unsets the active navigation transaction, if one exists.
+   *
+   * See [INavScope.finishNavTransaction].
+   */
   fun stop(scope: INavScope) {
-    val transaction = activeNavTransaction ?: return
-    val status = transaction.status ?: SpanStatus.OK
-    transaction.finish(status)
-    scope.unbindTransaction(transaction)
-    activeNavTransaction = null
+    scope.finishNavTransaction()
   }
 }
 
@@ -377,15 +354,15 @@ private class NavContext(private val scopes: INavScopes, private val options: Se
    * proper values to the transaction context instead.
    */
   fun <T : Any> updateTransaction(
-    transaction: ITransaction,
+    transaction: INavTransaction,
     scope: INavScope,
     backStack: BackStackData<T>,
   ) {
     if (scopes.options.isEnableScreenTracking) {
-      val appContext = transaction.contexts.app ?: scope.app ?: App()
+      val appContext = scope.app ?: App()
 
       appContext.viewNames = listOf(backStack.topEntryNormalized.name)
-      transaction.contexts.setApp(appContext)
+      transaction.setApp(appContext)
     }
 
     if (options.captureBackStack && backStack.capturedEntriesNormalized.isNotEmpty()) {

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

@@ -22,7 +22,8 @@ import io.sentry.compose.navigation3.lifecycle.NavScopes
  * **Thread safety**
  *
  * This class is ***not*** thread-safe. Invocations should be confined to the same thread as the
- * [LifecycleEventObserver] callbacks implemented by [NavScopes].
+ * [LifecycleEventObserver] callbacks through which the [NavLeaseCoordinator] observes the attached
+ * lifecycle.
  */
 internal class CoordinatedBackStackObserver<T : Any>(
   scopes: IScopes,