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

JPeer264 · web-flow · commit e62d70b777c8 · 2026-02-10T15:33:19.000Z
closes #18921 closes [JS-1526](https://linear.app/getsentry/issue/JS-1526/sessions-provide-more-options-to-control-session-creation) This adds a new `lifecycle` option to the `BrowserSessionIntegration`. New explained: - pagae: 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. - route (default): A session is created on page load and on every navigation change The default is to `route` to not introduce any breaking change ## Merge checklist - [ ] Add Sentry Docs issue to add this to [the docs](https://docs.sentry.io/platforms/javascript/configuration/integrations/browsersession/)
diff --git a/.size-limit.js b/.size-limit.js
@@ -156,7 +156,7 @@ module.exports = [
     path: 'packages/vue/build/esm/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '30 KB',
+    limit: '31 KB',
   },
   {
     name: '@sentry/vue (incl. Tracing)',
@@ -196,7 +196,7 @@ module.exports = [
     name: 'CDN Bundle (incl. Tracing, Logs, Metrics)',
     path: createCDNPath('bundle.tracing.logs.metrics.min.js'),
     gzip: true,
-    limit: '44 KB',
+    limit: '45 KB',
   },
   {
     name: 'CDN Bundle (incl. Replay, Logs, Metrics)',
diff --git a/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js b/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js
@@ -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({ lifecycle: 'page' })],
+});
diff --git a/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js b/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js
@@ -0,0 +1,12 @@
+let clickCount = 0;
+
+document.getElementById('navigate').addEventListener('click', () => {
+  clickCount++;
+  // Each click navigates to a different page
+  history.pushState({}, '', `/page-${clickCount}`);
+});
+
+document.getElementById('manual-session').addEventListener('click', () => {
+  Sentry.startSession();
+  Sentry.captureException('Test error from manual session');
+});
diff --git a/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html b/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <button id="navigate">Navigate via pushState</button>
+    <button id="manual-session">Manual session</button>
+  </body>
+</html>
diff --git a/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts b/dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts
@@ -0,0 +1,72 @@
+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 with page lifecycle.', 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 with page lifecycle.',
+  async ({ getLocalTestUrl, page }) => {
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    const sessionsPromise = getMultipleSentryEnvelopeRequests<SessionContext>(page, 10, {
+      url,
+      envelopeType: 'session',
+      timeout: 4000,
+    });
+
+    const manualSessionsPromise = getMultipleSentryEnvelopeRequests<SessionContext>(page, 10, {
+      envelopeType: 'session',
+      timeout: 4000,
+    });
+
+    const eventsPromise = getMultipleSentryEnvelopeRequests<SessionContext>(page, 10, {
+      envelopeType: 'event',
+      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);
+    expect(sessions[0].init).toBe(true);
+
+    // teardown and verify if nothing else got sent
+    await page.locator('#manual-session').click();
+
+    const newSessions = (await manualSessionsPromise).filter(session => session.init);
+    const events = await eventsPromise;
+
+    expect(newSessions.length).toBe(2);
+    expect(newSessions[0].init).toBe(true);
+    expect(newSessions[1].init).toBe(true);
+    expect(newSessions[1].sid).not.toBe(newSessions[0].sid);
+    expect(events).toEqual([
+      expect.objectContaining({
+        level: 'error',
+        message: 'Test error from manual session',
+      }),
+    ]);
+  },
+);
diff --git a/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js b/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js
@@ -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',
+});
diff --git a/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/subject.js b/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/subject.js
@@ -0,0 +1,6 @@
+let clickCount = 0;
+
+document.getElementById('navigate').addEventListener('click', () => {
+  clickCount++;
+  history.pushState({}, '', `/page-${clickCount}`);
+});
diff --git a/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/template.html b/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/template.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <button id="navigate">Navigate via pushState</button>
+  </body>
+</html>
diff --git a/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts b/dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts
@@ -0,0 +1,27 @@
+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 with route lifecycle (default).',
+  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);
+  },
+);
diff --git a/packages/browser/src/exports.ts b/packages/browser/src/exports.ts
@@ -102,5 +102,6 @@ export { globalHandlersIntegration } from './integrations/globalhandlers';
 export { httpContextIntegration } from './integrations/httpcontext';
 export { linkedErrorsIntegration } from './integrations/linkederrors';
 export { browserApiErrorsIntegration } from './integrations/browserapierrors';
+export { browserSessionIntegration } from './integrations/browsersession';
 
 export { lazyLoadIntegration } from './utils/lazyLoadIntegration';
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -76,7 +76,6 @@ export { makeBrowserOfflineTransport } from './transports/offline';
 export { browserProfilingIntegration } from './profiling/integration';
 export { spotlightBrowserIntegration } from './integrations/spotlight';
 export { cultureContextIntegration } from './integrations/culturecontext';
-export { browserSessionIntegration } from './integrations/browsersession';
 export { launchDarklyIntegration, buildLaunchDarklyFlagUsedHandler } from './integrations/featureFlags/launchdarkly';
 export { openFeatureIntegration, OpenFeatureIntegrationHook } from './integrations/featureFlags/openfeature';
 export { unleashIntegration } from './integrations/featureFlags/unleash';
diff --git a/packages/browser/src/integrations/browsersession.ts b/packages/browser/src/integrations/browsersession.ts
@@ -3,13 +3,30 @@ import { addHistoryInstrumentationHandler } from '@sentry-internal/browser-utils
 import { DEBUG_BUILD } from '../debug-build';
 import { WINDOW } from '../helpers';
 
+interface BrowserSessionOptions {
+  /**
+   * Controls the session lifecycle - when new sessions are created.
+   *
+   * - `'route'`: A session is created on page load and on every navigation.
+   *   This is the default behavior.
+   * - `'page'`: 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.
+   *
+   * @default 'route'
+   */
+  lifecycle?: 'route' | 'page';
+}
+
 /**
  * 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 lifecycle = options.lifecycle ?? 'route';
+
   return {
     name: 'BrowserSession',
     setupOnce() {
@@ -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 (lifecycle === 'route') {
+        // 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();
+          }
+        });
+      }
     },
   };
 });
