Support use of SentryNavEffect in multi-Activity and multi-Fragment applications #6345

Summary

Extend the Android Nav3 integration to support applications with multiple NavDisplay <> SentryNavEffect pairs hosted by different lifecycle owners.

Our initial Nav3 implementation assumed that only one SentryNavEffect would be active at a time. (Under the hood, SentryNavEffect writes to a shared, mutable IScope.) That's fine for single-Activity apps with singly-rooted nav graphs, but it won't work for multi-Activity or multi-Fragment applications where each Activity or Fragment has its own nav subgraph. (Usually, each subgraph will have its own NavDisplay <> SentryNavEffect pair.)

In particular, multiple SentryNavEffect instances may try to update the shared IScope when the host app transitions from one Activity / Fragment to the next. Under the current implementation, that can cause nav data to become stale or nav transactions to interfere with each other.

This issue tracks the work needed to extend Sentry Nav3 support to multi-Activity and multi-Fragment applications.

Setups to support

• A single-Activity app with one NavDisplay <> SentryNavEffect pair. (Already supported by the existing SentryNavEffect implementation.)
• A multi-Activity app where each Activity has at most one NavDisplay <> SentryNavEffect pair.
• A multi-Fragment app where each Fragment has at most one NavDisplay <> SentryNavEffect pair (and the host Activity or Activities have no SentryNavEffect(s) of their own).
• A ViewPager2 whose pages are Fragments, each with at most one NavDisplay <> SentryNavEffect pair.
• An Activity or Fragment with its own NavDisplay <> SentryNavEffect pair that stays visible beneath a DialogFragment or translucent Activity with its own pair.

Setups that will remain unsupported

• Sibling NavDisplay and SentryNavEffect pairs in the same Activity or Fragment.
• Nested NavDisplay and SentryNavEffect pairs in the same Activity or Fragment. (If you nest NavDisplays, consider using SentryNavEffect only with the outermost one.)
• SentryNavEffect instances in multiple Activities or Fragments that users can interact with at the same time, such as two Activities from the same app in multi-resume mode, or an Activity and hosted Fragments where the Activity and Fragments each have their own NavDisplay and SentryNavEffect pairs.
• SentryNavEffect instances in pages or tabs that share their host's lifecycle, such as Compose HorizontalPager pages, ViewPager2 pages that aren't Fragments, or tabs that are kept in the composition when inactive. (Those pages or tabs share one LifecycleOwner, so at most one can call SentryNavEffect.)

Proposed implementation

Supporting the new setups listed above requires coordinating multiple, simultaneously active SentryNavEffects and their updates to the current (mutable + shared) IScope vended by IScopes.

We can do so by replacing the IScopes instance our BackStackObserver already talks to with a smarter version (NavScopes) that can toggle between the shared underlying scope and a per-instance staged version, depending on whether the observer is associated with an incoming or outgoing SentryNavEffect. (Under the hood, NavScopes can use lease-based ownership to decide which effect can update the scope.)

That^^ let us keep updates to SentryNavEffect, BackStackObserver, etc. to a minimum. And it will make it easy to swap out our implementation in the future, should we ever hide our IScopes API behind a LocalSentrySpan-esque system (or any of a number of other possibilities).

Follow-up

Update the Android Navigation documentation to describe the supported multi-root lifecycle scenarios and current limitations.

References

• PR stack: #6301, #6302, #6304, #6305, #6307, #6309