Add automatic Navigation 3 instrumentation to the Sentry Android Gradle Plugin

Summary

Add Sentry Android Gradle Plugin support for automatically instrumenting Jetpack Navigation 3 applications.

Today, Nav3 users must manually:

1. Call SentryNavEffect alongside NavDisplay.
2. Provide a BackStackEntryMapper for their entire back stack.

This creates significant setup overhead and makes Nav3 instrumentation less discoverable than Nav2 instrumentation.

The SDK-side APIs and default mappers needed for this work are being introduced in sentry-java#6273.

Proposed approach

Instrument the internal rememberDecoratedNavEntries() call used by NavDisplay.

This appears preferable to instrumenting callers of NavDisplay because:

• The internal function has remained stable across Nav3 releases so far.
• The hook provides a precise and efficient instrumentation point.
• ASM does not need to scan arbitrary application code or handle all NavDisplay overloads.
• The approach should work across the existing Nav3 API variations.

The transformed code should install the SDK’s SentryNavAutoInstrumentation.Effect and configure it with the appropriate back-stack mapping behavior.

Back-stack entry mapping

Automatic instrumentation should use the SDK-provided default mapping behavior:

• Prefer the kotlinx.serialization @SerialName for NavKey types.
• Include serialized arguments where supported.
• Fall back to /unknown when a stable serial name cannot be determined.
• Preserve the ability for manually configured SentryNavEffect users to provide custom mappers.

The implementation should account for R8/minification. Serial names are compile-time constants and should remain available without requiring broad keep rules.

Configuration and privacy

Determine how automatic instrumentation should select the mapping behavior:

• Use the BackStackMappingType exposed by SentryNavAutoInstrumentation.
• Decide whether configuration belongs in SentryOptions, an Android manifest option, or both.
• Ensure serialized arguments follow the same sanitization and data-collection rules as the SDK-side implementation.
• Document how users can disable argument collection or automatic Nav3 instrumentation if needed.

Compatibility and safety

The implementation should:

• Support the currently supported Nav3 versions and define the compatibility policy for future versions.
• Avoid double instrumentation when an application already uses SentryNavEffect.
• Avoid conflicts when multiple NavDisplay/SentryNavEffect pairs are active.
• Clearly document unsupported combinations, including Nav2 and Nav3 instrumentation being active in the same application.
• Include canary coverage against representative Nav3 applications and API versions.
• Verify behavior in minified builds.

Acceptance criteria

• A Nav3 application receives navigation transactions, breadcrumbs, screen names, and back-stack context without manually calling SentryNavEffect.
• No manually implemented BackStackEntryMapper is required for the common @Serializable NavKey case.
• Existing manually configured Nav3 integrations continue to work unchanged.
• Automatic instrumentation can be disabled.
• Duplicate instrumentation is prevented or safely detected.
• Tests cover bytecode transformation, runtime behavior, minification, supported Nav3 versions, and failure/fallback cases.
• The Nav3 documentation explains automatic instrumentation, configuration, limitations, and manual setup.

References

• sentry-java#6273
• Jetpack Navigation 3 documentation
• Proposed instrumentation hook: rememberDecoratedNavEntries() inside NavDisplay