[0xadam-brown]

PR Stack (Nav3 Lifecycle)

• feat(android): Nav3 support for multi-Activity and multi-Fragment applications #6301
• ref(android): [Nav3 Lifecycle 1] Add NavLeaseCoordinator #6302
• ref(android): [Nav3 Lifecycle 2] Add lease-aware NavScopes facade #6304
• feat(android): [Nav3 Lifecycle 3] Coordinate SentryNavEffect access to current IScope #6305
• test(android): [Nav3 Lifecycle 4] Integration tests for lifecycle handoffs #6307
• feat(sample): [Nav3 Lifecycle 5] Add Nav3 lifecycle scenarios to sample app #6309

---

📜 Description

PR stack lets us support Nav3 for app architectures involving multiple NavDisplay <> SentryNavEffect pairs, subject to certain limitations (see the "Still not supported" list below). Prior to this stack, we assumed only one NavDisplay <> SentryNavEffect pair would be active at a time.

Supported

1. A single-Activity app with one NavDisplay <> SentryNavEffect pair.
2. A multi-Activity app where each Activity has its own NavDisplay <> SentryNavEffect pair.
3. A multi-Fragment app where each Fragment has its own NavDisplay <> SentryNavEffect pair.
4. A ViewPager2 whose pages are Fragments, each with its own NavDisplay <> SentryNavEffect pair.
5. An Activity or Fragment with its own NavDisplay that stays visible beneath a DialogFragment or translucent Activity with its own NavDisplay.

Before this PR stack, we only supported (1) and its functional equivalents.

Still not supported

1. Nested NavDisplay <> SentryNavEffect pairs in the same Activity or Fragment.
2. Side-by-side NavDisplay <> SentryNavEffect pairs in the same Activity or Fragment.
3. 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.
4. 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 kept in the composition at once. (Those pages or tabs share one LifecycleOwner, so at most one can call SentryNavEffect.)

🔎 The basic approach

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

Like all forms of state management around Android lifecycles + shared mutable state, that code isn't exactly simple. To keep things manageable (and easy to update!), I've been careful to sequester all coordination logic to the new .navigation3.lifecycle package.

The basic idea was to replace the IScopes instance our BackStackObserver already talked to with a smarter version (NavScopes) that could toggle between the shared underlying scope and a per-instance staged version, depending on whether the observer was associated with the incoming or outgoing SentryNavEffect. (Under the hood, NavScopes relies on lease-based ownership to decide who can update the scope, which is overseen by the new NavLeaseCoordinator.)

That^^ let me keep updates to SentryNavEffect, BackStackObserver, etc. to a minimum, and it makes 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) 🎉 .

💡 Motivation and Context

Lets us support the multi-Activity and multi-Fragment app setups listed above. Those setups are common, and without the changes here, spans and nav state would be incorrect when transitioning between Activities or Fragments.

That's worrisome, because Activity / Fragment startup logic is a common source of bugs and crashes, so properly attributing Sentry data there is especially worthwhile.

addresses: JAVA-785

💚 How did you test it?

Each stack branch is formatted, API-dumped, built, and tested independently before its PR is opened.

📝 Checklist

• I added GH Issue ID & Linear ID
• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.
• Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

• Merge the stack from bottom to top using merge commits, then squash-merge this collection PR into main.
• Update our Android Navigation page in sentry-docs: See sentry-docs #20137

#skip-changelog

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 723b40a

[sentry]

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.61.1 (1)	release

⚙️ sentry-android Build Distribution Settings

[romtsn]

I think configureScope already catches everything, so no exception gets to the host app, and I don't think we have this pattern of the SDK protectcting itself from throwing scope observers. Do we want to introduce this here? If not, we could drop a good chunk from unregisterCandidate and transferLeaseTo.

[romtsn]

Q: is this the min supported version that our integration can work with?