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

Merged
JPeer264 merged 5 commits into from
Feb 10, 2026
Merged

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
5 commits
Select commit Hold shift + click to select a range
49dc62a
feat(browser): Add mode option for the browser session integration
JPeer264 Jan 27, 2026
ff4deee
feat: BrowserSessionIntegration available in CDN/bundle
JPeer264 Jan 30, 2026
afaff66
test: Verify if only one session exists
JPeer264 Feb 5, 2026
ef88277
ref: mode -> lifecycle
JPeer264 Feb 5, 2026
ba2564f
fixup! ref: mode -> lifecycle
JPeer264 Feb 10, 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
4 changes: 2 additions & 2 deletions .size-limit.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down
9 changes: 9 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js
View file
Open in desktop
Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});
12 changes: 12 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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');
});
10 changes: 10 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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>
72 changes: 72 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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);
Comment on lines +48 to +52

@Lms24Lms24Jan 28, 2026•
edited
Loading

Copy link
Copy Markdown
Member

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

@JPeer264JPeer264Jan 30, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these

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',
}),
]);
},
);
8 changes: 8 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js
View file
Open in desktop
Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js
View file
Open in desktop
Original file line numberDiff line numberDiff 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/route-lifecycle/template.html
View file
Open in desktop
Original file line numberDiff line numberDiff 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>
27 changes: 27 additions & 0 deletions dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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);
},
);
1 change: 1 addition & 0 deletions packages/browser/src/exports.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
1 change: 0 additions & 1 deletion packages/browser/src/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down
37 changes: 28 additions & 9 deletions packages/browser/src/integrations/browsersession.ts
View file
Open in desktop
Original file line numberDiff line numberDiff 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';

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() {
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 (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();
}
});
}
},
};
});
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

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

 Merged

JPeer264
merged 5 commits into

from

Feb 10, 2026
 Merged


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


5 commits


Select commit
Hold shift + click to select a range
49dc62a

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


JPeer264 Jan 27, 2026
ff4deee

feat: BrowserSessionIntegration available in CDN/bundle


JPeer264 Jan 30, 2026
afaff66

test: Verify if only one session exists


JPeer264 Feb 5, 2026
ef88277

ref: mode -> lifecycle


JPeer264 Feb 5, 2026
ba2564f

fixup! ref: mode -> lifecycle


JPeer264 Feb 10, 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


4 changes: 2 additions & 2 deletions
.size-limit.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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)',
Expand DownExpand Up@@ -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)',
Expand Down

9 changes: 9 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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({ lifecycle: 'page' })],
});

12 changes: 12 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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');
});

10 changes: 10 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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>

72 changes: 72 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/page-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);

Comment on lines

+48
 to 
+52

@Lms24Lms24Jan 28, 2026•

edited

Loading

Copy link


Copy Markdown

Member
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
@JPeer264JPeer264Jan 30, 2026

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

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

Those are very valid points. I'll try to implement these
 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',
 }),
 ]);
 },
);

8 changes: 8 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/init.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/subject.js

View file


Open in desktop

Original file line numberDiff line numberDiff 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/route-lifecycle/template.html

View file


Open in desktop

Original file line numberDiff line numberDiff 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>

27 changes: 27 additions & 0 deletions
dev-packages/browser-integration-tests/suites/sessions/route-lifecycle/test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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);
 },
);

1 change: 1 addition & 0 deletions
packages/browser/src/exports.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';

1 change: 0 additions & 1 deletion
packages/browser/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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';
Expand Down

37 changes: 28 additions & 9 deletions
packages/browser/src/integrations/browsersession.ts

View file


Open in desktop

Original file line numberDiff line numberDiff 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';

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() {
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 (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();
 }
 });
 }
 },
 };
});
Loading