Allow use of sessionStorage in browserSessionIntegration to more accurately count sessions for MPAs

Description

Session updates we send from the Browser SDK are currently per pageview, leading to more sessions than is commonly understood for MPAs. We find that Sessions likely should have the same lifetime as a Session Replay session. For this we should introduce an option in the browserSessionIntegration that allows a user to configure a persistence model using sessionStorage to more accurately collect number of sessions.

Strawman proposal: We add a sessioIntegration() with the following options:

interface SessionIntegrationOptions {
  /**
   * The storage type that the SDK uses to store a Session ID that is used for Sessions and Release Health in Sentry.
   * 
   * Possible values:
   * 
   * - `"sessionStorage"` (default) The Session ID is persisted to the browser's `sessionStorage`. Sessions will persist across hard-navigations on the same origin.
   * - `"memory"` The Session ID is stored in memory. Hard-navigations will produce new sessions.
   * 
   * Defaults to `"sessionStorage"`.
   */
  persistence?: 'sessionStorage' | 'memory'
}

The persistence name coincides with a similar/same option and behavior in Posthog. It's just a great name for this option: https://posthog.com/docs/libraries/js#persistence

Just wanted to mention I think this is a solid plan. Defaulting to sessionStorage with a clear opt-out.

Session Replay relies on sessionStorage and not once we heard this being the reason why someone wouldn't want to use it.

A bigger question would be relying on localStorage. Although that could be an option for users who'd like to have traces connect across tabs, and surviving restarts. But sessionStorage seems like a great improvement to the product without compromising privacy.

+1 on making it opt-out in other words, makeing sessionStorage default
We are doing this with the intention to provide a better service, it is communicated in a major and we are not storing any sensitive data in there so a very clear case for me

This has made another round among stakeholders, we will have to make the usage of sessionStorage opt-in. Which will make this a non-breaking change and not part of v9.

@lforst

@lforst I'm looking into implementing sessions on Flutter web, should sessionStorage be opt-in here as well or are we free to have it enabled by default?

@buenaflor

@buenaflor having a privacy-first stance, sessionStorage would also need to be opt-in. It cannot be the default.

@logaretm

@logaretm and I just had a discussion around browser session lifecycles which I wanna write down here for posterity. The sessionstorage mode would still need to be opt-in, no change about that. The more interesting question is:

Do we synchronize the browser session in this mode with the Replay session?

After talking about it, we tend towards "No" for the following reasons:

A replay only has a tangential "replayId", it doesn't actually track a session
A replay's max. time is 60 minutes. If we sync the browser SDK's session to this, we cannot record longer times.
Users can start and stop their own sessions if they choose to do so (opt out of browserSessionIntegration and use Sentry.startSession() et.al.). If we sync replays with these sessions, this can lead to too long or very short replays
Assuming we tag telemetry (logs, metrics, spans, eventually errors) with the browser SDK's session.id (getting there), sudden changes in this id (e.g. because a replay reaches max length or is stopped for other reasons) shouldn't necessarily also change SDK's session.

Instead, we could see a way forward with the following behaviour:

If replay is not used:
- SDK session defaults to page (as described in Make page the default browser session lifecycle mode #21241), as we cannot by default opt into anything longer than that
- Users can opt into storing the SDK session in sessionStorage as described in this issue, with a lifecycle/behaviour of our choosing (max time, inactivity, etc)
If replay is used:
- We switch the SDK's session to sessionStorage because users already opted into sessionStorage by using Replay.
- That is, unless users explicitly configure a different lifecycle mode in browserSessionIntegration

For this to work, the browser SDK's sessionStorage session lifecycle must permit sessions to at least last as long as a replay session. This allows us to:

have sessions with potentially multiple replay recordings
not have multiple browser sessions mapping to one replay
In practise, I think having a session last longer than 60 minutes is fine but we'll need an upper limit either way

The main weaknesses of this idea:

implicit use of sessionStorage via replayIntegration opt in. Users might not be aware of this. ~~Need to confirm with legal if this is fine.~~ we already did this and it is fine (we have a DACI that explicitly includes this decision)
users manually setting a shorter session breaking the "we don't want multiple sessions mapping to one replay" constraint

Navigation Menu

Repository navigation

Allow use of `sessionStorage` in `browserSessionIntegration` to more accurately count sessions for MPAs #14478

Description

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Allow use of sessionStorage in browserSessionIntegration to more accurately count sessions for MPAs #14478

Description

Description

Activity

lforst commented on Dec 2, 2024

bruno-garcia commented on Jan 7, 2025

HazAT commented on Jan 7, 2025

lforst commented on Jan 9, 2025

buenaflor commented on Mar 25, 2025

lforst commented on Mar 26, 2025

Lms24 commented on May 29, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Allow use of `sessionStorage` in `browserSessionIntegration` to more accurately count sessions for MPAs #14478