feat(nav3): Introduce BackStackEntryMappers for Nav3 + prepare for SAGP auto-instrumentation

[0xadam-brown]

📜 Description

Introduce sentry-java changes needed to support Nav3 auto-instrumentation via the Sentry Android Gradle Plugin.

Those changes have the happy side effect of introducing some helpful out-of-the-box implementations of BackStackEntryMapper so most developers won't have to implement their own.

See "Motivation and Context" below for some helpful details.

💡 Motivation and Context

The basic idea:

[1] The new SentryNavAutoInstrumentation.Effect acts as a stable API for SAGP code that lets it avoid having to care about Compose compiler plugin modifications to SentryNavEffect's parameters.

[2] Effect also lets us expose a BackStackMappingType rather than the actual BackStackEntryMapper exposed by SentryNavEffect.

[3] That mapping type can be configured externally, either by a new SentryOptions.dataCollection.navigationParams-esque boolean, or by a toggle exposed via an AndroidManifest.

[4] The flexibility is [3] means we don't have to wait on folks to approve (or deny) our request to add a new boolean to SentryOptions.dataCollection, since those have to be coordinated across SDKs and formally specified.

A helpful addition:

The spec for the recently introduced Data Collection API requires that all sensitive denylist values be scrubbed from HTTP headers, cookies, and URL params (link). This PR subjects arguments serialized via the new BackStackEntryMapper.serializeNameWithArguments() to similar scrubbing.

⚠️ Callouts

Note that serialName() and serialNameWithArguments() fall back to "/unknown" if a @SerialName isn't available, rather than our original idea of falling back to the entry's class name with the help of this KEEP rule:

  -keep,allowshrinking class * implements androidx.navigation3.runtime.NavKey

That fallback would help NavKey types that aren't @serializable. Turns out they're very uncommon, as a search against GitHub shows (about 23,200 hits for "NavKey" but the API returns at most the first 1,000, which came from 749 repos):

Results	Total	All @Serializable	Some not	None
Concrete NavKey types	2,871	2,836 (98.8%)	—	35 (1.2%)
Files	585	560	8	17
Repos	503	479 (95%)	9	15

So about 99% of NavKey types are @Serializable, and about 95% of repos make every NavKey type serializable. And so I've refrained from adding the KEEP rule in order to avoid interfering with R8 on behalf of what looks like a de minimis corner case. Chime in if you think differently!

💚 How did you test it?

📝 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

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

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

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Unreleased" section. Make sure the entry includes this PR's number.

Example:

## Unreleased

### Features

- Introduce BackStackEntryMappers for Nav3 + prepare for SAGP auto-instrumentation ([#6273](https://github.com/getsentry/sentry-java/pull/6273))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description or adding a skip-changelog label.

Generated by 🚫 dangerJS against f281289

[sentry]

📲 Install Builds

Android

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

⚙️ sentry-android Build Distribution Settings