Skip to content

feat(browser): Add mode option for the browser session integration #18997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JPeer264 wants to merge 2 commits into
base: develop
Choose a base branch
from
+147 −10
Open

feat(browser): Add mode option for the browser session integration #18997

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba9ff45
feat(browser): Add mode option for the browser session integration
JPeer264 Jan 27, 2026
452d0c4
fixup! feat(browser): Add mode option for the browser session integra…
JPeer264 Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .size-limit.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ module.exports = [
path: createCDNPath('bundle.tracing.logs.metrics.min.js'),
gzip: false,
brotli: false,
limit: '130 KB',
limit: '131 KB',
},
{
name: 'CDN Bundle (incl. Tracing, Replay) - uncompressed',
Expand Down
8 changes: 8 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/navigation-mode/init.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
import * as Sentry from '@sentry/browser';

window.Sentry = Sentry;

Sentry.init({
dsn: 'https://public@dsn.ingest.sentry.io/1337',
release: '0.1',
});
6 changes: 6 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/navigation-mode/subject.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
let clickCount = 0;

document.getElementById('navigate').addEventListener('click', () => {
clickCount++;
history.pushState({}, '', `/page-${clickCount}`);
});
9 changes: 9 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/navigation-mode/template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>
<button id="navigate">Navigate via pushState</button>
</body>
</html>
24 changes: 24 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/navigation-mode/test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import { expect } from '@playwright/test';
import type { SessionContext } from '@sentry/core';
import { sentryTest } from '../../../utils/fixtures';
import { getMultipleSentryEnvelopeRequests } from '../../../utils/helpers';

sentryTest('should start new sessions on pushState navigation in default mode.', async ({ getLocalTestUrl, page }) => {
const url = await getLocalTestUrl({ testDir: __dirname });

const sessionsPromise = getMultipleSentryEnvelopeRequests<SessionContext>(page, 10, {
url,
envelopeType: 'session',
timeout: 4000,
});

await page.waitForSelector('#navigate');

await page.locator('#navigate').click();
await page.locator('#navigate').click();
await page.locator('#navigate').click();

const sessions = (await sessionsPromise).filter(session => session.init);

expect(sessions.length).toBe(3);
});
9 changes: 9 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/single-mode/init.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import * as Sentry from '@sentry/browser';

window.Sentry = Sentry;

Sentry.init({
dsn: 'https://public@dsn.ingest.sentry.io/1337',
release: '0.1',
integrations: [Sentry.browserSessionIntegration({ mode: 'single' })],
});
7 changes: 7 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/single-mode/subject.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
let clickCount = 0;

document.getElementById('navigate').addEventListener('click', () => {
clickCount++;
// Each click navigates to a different page
history.pushState({}, '', `/page-${clickCount}`);
});
9 changes: 9 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/single-mode/template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>
<button id="navigate">Navigate via pushState</button>
</body>
</html>
45 changes: 45 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/single-mode/test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import { expect } from '@playwright/test';
import type { SessionContext } from '@sentry/core';
import { sentryTest } from '../../../utils/fixtures';
import { getMultipleSentryEnvelopeRequests } from '../../../utils/helpers';

sentryTest('should start a session on pageload in single mode.', async ({ getLocalTestUrl, page }) => {
const url = await getLocalTestUrl({ testDir: __dirname });

const sessions = await getMultipleSentryEnvelopeRequests<SessionContext>(page, 1, {
url,
envelopeType: 'session',
timeout: 2000,
});

expect(sessions.length).toBeGreaterThanOrEqual(1);
const session = sessions[0];
expect(session).toBeDefined();
expect(session.init).toBe(true);
expect(session.errors).toBe(0);
expect(session.status).toBe('ok');
});

sentryTest(
'should NOT start a new session on pushState navigation in single mode.',
async ({ getLocalTestUrl, page }) => {
const url = await getLocalTestUrl({ testDir: __dirname });

const sessionsPromise = getMultipleSentryEnvelopeRequests<SessionContext>(page, 10, {
url,
envelopeType: 'session',
timeout: 4000,
});

await page.waitForSelector('#navigate');

await page.locator('#navigate').click();
await page.locator('#navigate').click();
await page.locator('#navigate').click();

const sessions = (await sessionsPromise).filter(session => session.init);

expect(sessions.length).toBe(1);
Comment on lines +38 to +42
Copy link
Member

@Lms24 Lms24 Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

l: What I like to do when I test that something is not sent, is to await an event after navigating so that we have some time before ending the tests. I guess in this case, we could wait for an error or a transaction event. There's still an assumption here that the session would have been sent before that event but I think that's reasonable and better than not waiting at all or waiting for a a specific time.

We could even make it more deterministic by:

  1. going to the page
  2. awaiting for the init session
  3. registering the request listener for additional sessions
  4. navigating
  5. waiting for the unrelated event
  6. asserting that no more session envelopes have been sent

expect(sessions[0].init).toBe(true);
},
);
1 change: 1 addition & 0 deletions packages/browser/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ export { makeBrowserOfflineTransport } from './transports/offline';
export { browserProfilingIntegration } from './profiling/integration';
export { spotlightBrowserIntegration } from './integrations/spotlight';
export { browserSessionIntegration } from './integrations/browsersession';
export type { BrowserSessionOptions } from './integrations/browsersession';
export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integrations/featureFlags/launchdarkly';
export { openFeatureIntegration, OpenFeatureIntegrationHook } from './integrations/featureFlags/openfeature';
export { unleashIntegration } from './integrations/featureFlags/unleash';
Expand Down
37 changes: 28 additions & 9 deletions packages/browser/src/integrations/browsersession.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,30 @@ import { addHistoryInstrumentationHandler } from '@sentry-internal/browser-utils
import { DEBUG_BUILD } from '../debug-build';
import { WINDOW } from '../helpers';

export interface BrowserSessionOptions {
/**
* Controls when sessions are created.
*
* - `'single'`: A session is created once when the page is loaded. Session is not
* updated on navigation. This is useful for webviews or single-page apps where
* URL changes should not trigger new sessions.
* - `'navigation'`: A session is created on page load and on every navigation.
* This is the default behavior.
*
* @default 'navigation'
*/
mode?: 'single' | 'navigation';
Copy link
Member

@s1gr1d s1gr1d Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not 100% sure about the naming here, as it's only clear when reading the JS doc. A suggestion:

sessionMode: 'navigation' | 'only-pageload'

Hm, now that I think more about it, it's probably fine because this is an option in the browserSessionIntegration and it should be clear that this is about the session. So the naming would actually work already (just leaving this to share my thoughts).

Copy link
Member Author

@JPeer264 JPeer264 Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uuuuuuh, I actually like only-pageload. However, it seems too technical correct - it could be that "only-pageload" implies that it doesn't track the session further 🤔

@Lms24 wdyt? To get a third opinion here :)

Copy link
Member

@Lms24 Lms24 Jan 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm yeah, "only-pageload" to me also implies something like "we only track sessions for the pageload and stop afterwards".
Let's think about this, also from a perspective of potentially adding a third mode for persisting the id in sessionStorage in the future. So mentally, it should correlate to "short -> medium -> long".

How about:

  1. lifecycle: 'route' | 'page' | 'tab'
  2. lifecycle: 'navigation' | 'pageload' | 'tab'

1 has the advantage that it's very descriptive, but confusion could come from "page". I think this is minimal and also kinda works anyway because it's primarily relevant for Single Page applications".

2 is a bit more technical but correlates well with established Sentry terms.

I think with the proper JSDoc (which is already there xD), both would work well. Especially if we pair these with lifecycle since this more directly implies session life time than "mode" IMHO. Fully realizing I said other things offline, so sorry for throwing yet more options into the ring. Thoughts?

fwiw, Gemini clearly prefers 1 😅

}

/**
* When added, automatically creates sessions which allow you to track adoption and crashes (crash free rate) in your Releases in Sentry.
* More information: https://docs.sentry.io/product/releases/health/
*
* Note: In order for session tracking to work, you need to set up Releases: https://docs.sentry.io/product/releases/
*/
export const browserSessionIntegration = defineIntegration(() => {
export const browserSessionIntegration = defineIntegration((options: BrowserSessionOptions = {}) => {
const mode = options.mode ?? 'navigation';

return {
name: 'BrowserSession',
setupOnce() {
Expand All @@ -26,14 +43,16 @@ export const browserSessionIntegration = defineIntegration(() => {
startSession({ ignoreDuration: true });
captureSession();

// We want to create a session for every navigation as well
addHistoryInstrumentationHandler(({ from, to }) => {
// Don't create an additional session for the initial route or if the location did not change
if (from !== undefined && from !== to) {
startSession({ ignoreDuration: true });
captureSession();
}
});
if (mode === 'navigation') {
// We want to create a session for every navigation as well
addHistoryInstrumentationHandler(({ from, to }) => {
// Don't create an additional session for the initial route or if the location did not change
if (from !== undefined && from !== to) {
startSession({ ignoreDuration: true });
captureSession();
}
});
}
},
};
});
Loading