Skip to content

feat(nav3): Add built-in BackStackEntryMappers for kotlinx.serialization - #6696

Open
0xadam-brown wants to merge 1 commit into
mainfrom
feat/nav3-serial-name-mappers-base
Open

0xadam-brown wants to merge 1 commit into
mainfrom
feat/nav3-serial-name-mappers-base

Conversation

@0xadam-brown

@0xadam-brown 0xadam-brown commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

PR Stack (Nav3 Serial Name Mappers)


📜 Description

Introduces two built-in BackStackEntryMappers mappers for kotlinx.serialization so host apps don't have to define their own.

For an entry like this...

@Serializable
@SerialName("ProductDetailScreen")
data class ProductDetail(val productId: String = "123", val authToken: String = "secret",)

...the built-in mappers create Sentry data like this:

Built-in mapper Entry name Entry arguments
SerialName "/ProductDetailScreen" n/a
SerialNameAndProperties "/ProductDetailScreen" {"productId": "123", "authToken": "[Filtered]" }

The high-level processing path:

For the top entry in the host app's nav stack
  → look up kotlinx serializer + descriptor
    → derive stable serial name
      → optionally deserialize properties as arguments
        → filter sensitive properties
          → enforce argument size / structure limits
            → record serial name + (optional) arguments as navigation data

Failure modes

  • If an entry can't be deserialized or its name isn't recoverable, it's given the name "/unknown"
  • If an entry's arguments can't be deserialized, the entity keeps its name but the arguments are dropped and given a dropped_by_sentry reason.

💡 Motivation and Context

With Nav3, host apps manage their own nav back stack, which they implement as a list of arbitrarily typed entries. In order for us to display telemetry for those entries, someone has extract a Sentry name (e.g., ProductDetailScreen) and zero or more arguments (e.g., productId="abc1234") from them.

Before

Prior to this PR stack, extracting that data was the responsibility of host apps, via custom implementations of the BackStackEntryMapper interface, like this:

 SentryNavEffect(
    backStack = navBackStack,
    // The host app has to implement its own custom mapper
    backStackEntryMapper = BackStackEntryMapper<NavKey> { entry -> 
      when (entry) {
        is Home -> SentryBackStackEntry(Home.serializer().descriptor.serialName)
        is ProductDetail -> SentryBackStackEntry(
          name = ProductDetail.serializer().descriptor.serialName,
          arguments = mapOf("product_id" to entry.productId)
        )
       // And so on for every nav destination in app...
    },
    options = SentryNavOptions(),
  )

After

This PR stack introduces two convenience mappers that host apps can use ii) instead of implementing their own or ii) as a fallback within their own custom mapper.

Like this:

  SentryNavEffect(
    backStack = navBackStack,
    backStackEntryMapper = BackStackEntryMapper.SerialNameAndProperties,
    options = SentryNavOptions(),
  )

Uses a new built-in mapper directly.

Or this:

SentryNavEffect(
    backStack = navBackStack,
    backStackEntryMapper = BackStackEntryMapper.SerialNameAndProperties.map(entry)
      ?.let { mapped ->
         SentryBackStackEntry(
           name = mapped.name,
           arguments = mapped.arguments?.filterKeys { it != "userEmail" },
         )
    },
    options = SentryNavOptions(),
  )

Uses a built-in mapper but filters specific properties from all entries (e.g., because they contain PII).

Or this:

 SentryNavEffect(
    backStack = navBackStack,
    backStackEntryMapper = BackStackEntryMapper<NavKey> { entry -> 
      when (entry) {
        is ProductDetail -> SentryBackStackEntry(
          name = ProductDetail.serializer().descriptor.serialName,
          arguments = mapOf("product_id" to entry.productId)
        )

        else -> BackStackEntryMapper.SerialNameAndProperties.map(entry)
    },
    options = SentryNavOptions(),
  )

Uses a custom mapper to special-case entries as needed, and falls back back to a built-in mapper for the rest.

This PR stack covers all the gory details of what introducing those built-in mappers requires. Have fun!

addresses: JAVA-787 (link)

🔍 Due diligence

See the "Callouts" section in #6707 for a discussion of the performance impact of this PR stack, as well as leak memory concerns, and potential for crashing the host app. (Spoiler alert: no issues were found.)

💚 How did you test it?

(See individual PRs.)

📝 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

  • Update sentry-docs.
  • Implement auto-instrumentation in SAGP.
  • Introduce shim for the built-in mappers that our auto-instrumentation can invoke.

#skip-changelog

@github-actions

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

Generated by 🚫 dangerJS against 3dc7c0a

@sentry

sentry Bot commented Nov 20, 2026

Copy link
Copy Markdown

📲 Install Builds

Android

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

⚙️ sentry-android Build Distribution Settings

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant