enable $web_vitals reporting when cookieless mode is enabled

eli-r-ph · eli-r-ph · commit 0be0de34da3d · 2026-05-18T18:01:51.000-07:00
diff --git a/packages/browser/src/__tests__/extensions/web-vitals.test.ts b/packages/browser/src/__tests__/extensions/web-vitals.test.ts
@@ -6,7 +6,7 @@ import { PostHog } from '../../posthog-core'
 import { FlagsResponse, PerformanceCaptureConfig, RemoteConfig, SupportedWebVitalsMetrics } from '../../types'
 import { assignableWindow } from '../../utils/globals'
 import { DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS, FIFTEEN_MINUTES_IN_MILLIS } from '../../extensions/web-vitals'
-import { WEB_VITALS_ENABLED_SERVER_SIDE, WEB_VITALS_ALLOWED_METRICS } from '../../constants'
+import { WEB_VITALS_ENABLED_SERVER_SIDE, WEB_VITALS_ALLOWED_METRICS, COOKIELESS_MODE_FLAG_PROPERTY } from '../../constants'
 
 jest.useFakeTimers()
 
@@ -242,6 +242,91 @@ describe('web vitals', () => {
         }
     )
 
+    describe('cookieless_mode (no SessionIdManager)', () => {
+        const expectedEmittedWebVitalsCookieless = (name: string) => ({
+            $current_url: 'http://localhost/',
+            timestamp: expect.any(Number),
+            name: name,
+            value: 123.45,
+            extra: 'property',
+        })
+
+        beforeEach(async () => {
+            beforeSendMock.mockClear()
+            onLCPCallback = undefined
+            onCLSCallback = undefined
+            onFCPCallback = undefined
+            onINPCallback = undefined
+
+            posthog = await createPosthogInstance(uuidv7(), {
+                before_send: beforeSendMock,
+                cookieless_mode: 'always',
+                capture_performance: { web_vitals: true, web_vitals_allowed_metrics: ['CLS', 'FCP'] },
+                capture_pageview: false,
+            })
+
+            expect(posthog.sessionManager).toBeUndefined()
+
+            loadScriptMock.mockImplementation((_ph, _path, callback) => {
+                assignableWindow.__PosthogExtensions__ = {}
+                assignableWindow.__PosthogExtensions__.postHogWebVitalsCallbacks = {
+                    onLCP: (cb: any) => {
+                        onLCPCallback = cb
+                    },
+                    onCLS: (cb: any) => {
+                        onCLSCallback = cb
+                    },
+                    onFCP: (cb: any) => {
+                        onFCPCallback = cb
+                    },
+                    onINP: (cb: any) => {
+                        onINPCallback = cb
+                    },
+                }
+                callback()
+            })
+
+            assignableWindow.__PosthogExtensions__ = {}
+            assignableWindow.__PosthogExtensions__.loadExternalDependency = loadScriptMock
+
+            posthog.webVitalsAutocapture!.onRemoteConfig({
+                capturePerformance: { web_vitals: true },
+            } as unknown as FlagsResponse)
+
+            expect(posthog.webVitalsAutocapture!.allowedMetrics).toEqual(['CLS', 'FCP'])
+        })
+
+        it('emits web vitals without nested $session_id or $window_id; sets $cookieless_mode on payload', async () => {
+            onCLSCallback?.({ name: 'CLS', value: 123.45, extra: 'property' })
+            onFCPCallback?.({ name: 'FCP', value: 123.45, extra: 'property' })
+
+            expect(beforeSendMock).toBeCalledTimes(1)
+
+            const payload = beforeSendMock.mock.calls[0][0]
+            expect(payload.event).toBe('$web_vitals')
+            expect(payload.properties[COOKIELESS_MODE_FLAG_PROPERTY]).toBe(true)
+            expect(payload.properties.$web_vitals_CLS_event).toEqual(expectedEmittedWebVitalsCookieless('CLS'))
+            expect(payload.properties.$web_vitals_FCP_event).toEqual(expectedEmittedWebVitalsCookieless('FCP'))
+            expect(payload.properties.$web_vitals_CLS_event).not.toHaveProperty('$session_id')
+            expect(payload.properties.$web_vitals_CLS_event).not.toHaveProperty('$window_id')
+            expect(payload.properties.$web_vitals_FCP_event).not.toHaveProperty('$session_id')
+            expect(payload.properties.$web_vitals_FCP_event).not.toHaveProperty('$window_id')
+        })
+
+        it('emits on delayed flush without nested session ids when only one metric is captured', async () => {
+            onCLSCallback?.({ name: 'CLS', value: 123.45, extra: 'property' })
+
+            jest.advanceTimersByTime(DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
+
+            expect(beforeSendMock).toBeCalledTimes(1)
+            const payload = beforeSendMock.mock.calls[0][0]
+            expect(payload.event).toBe('$web_vitals')
+            expect(payload.properties[COOKIELESS_MODE_FLAG_PROPERTY]).toBe(true)
+            expect(payload.properties.$web_vitals_CLS_event).not.toHaveProperty('$session_id')
+            expect(payload.properties.$web_vitals_CLS_event).not.toHaveProperty('$window_id')
+        })
+    })
+
     describe('web_vitals_attribution config', () => {
         it.each([
             [undefined, false],
diff --git a/packages/browser/src/extensions/web-vitals/index.ts b/packages/browser/src/extensions/web-vitals/index.ts
@@ -1,11 +1,12 @@
 import { PostHog } from '../../posthog-core'
-import { PostHogConfig, RemoteConfig, SupportedWebVitalsMetrics } from '../../types'
+import { RemoteConfig, SupportedWebVitalsMetrics } from '../../types'
 import { createLogger } from '../../utils/logger'
 import { isBoolean, isNullish, isNumber, isUndefined, isObject } from '@posthog/core'
 import { WEB_VITALS_ALLOWED_METRICS, WEB_VITALS_ENABLED_SERVER_SIDE } from '../../constants'
 import { assignableWindow, window, location } from '../../utils/globals'
 import { maskQueryParams } from '../../utils/request-utils'
 import { PERSONAL_DATA_CAMPAIGN_PARAMS, MASKED } from '../../utils/event-utils'
+import { extendArray } from '../../utils'
 
 const logger = createLogger('[Web Vitals]')
 
@@ -30,38 +31,36 @@ export class WebVitalsAutocapture {
         this.startIfEnabled()
     }
 
-    /** Shorthand for performance config to reduce bundle size */
-    private get _perfConfig(): PostHogConfig['capture_performance'] {
-        return this._instance.config.capture_performance
-    }
-
     public get allowedMetrics(): SupportedWebVitalsMetrics[] {
-        const clientConfigMetricAllowList: SupportedWebVitalsMetrics[] | undefined = isObject(this._perfConfig)
-            ? this._perfConfig?.web_vitals_allowed_metrics
+        const clientConfigMetricAllowList: SupportedWebVitalsMetrics[] | undefined = isObject(
+            this._instance.config.capture_performance
+        )
+            ? this._instance.config.capture_performance?.web_vitals_allowed_metrics
             : undefined
         return !isNullish(clientConfigMetricAllowList)
             ? clientConfigMetricAllowList
             : this._instance.persistence?.props[WEB_VITALS_ALLOWED_METRICS] || ['CLS', 'FCP', 'INP', 'LCP']
     }
 
     public get flushToCaptureTimeoutMs(): number {
-        const clientConfig: number | undefined = isObject(this._perfConfig)
-            ? this._perfConfig.web_vitals_delayed_flush_ms
+        const clientConfig: number | undefined = isObject(this._instance.config.capture_performance)
+            ? this._instance.config.capture_performance.web_vitals_delayed_flush_ms
             : undefined
         return clientConfig || DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS
     }
 
     public get useAttribution(): boolean {
-        const clientConfig: boolean | undefined = isObject(this._perfConfig)
-            ? this._perfConfig.web_vitals_attribution
+        const clientConfig: boolean | undefined = isObject(this._instance.config.capture_performance)
+            ? this._instance.config.capture_performance.web_vitals_attribution
             : undefined
         return clientConfig ?? false
     }
 
     public get _maxAllowedValue(): number {
         const configured =
-            isObject(this._perfConfig) && isNumber(this._perfConfig.__web_vitals_max_value)
-                ? this._perfConfig.__web_vitals_max_value
+            isObject(this._instance.config.capture_performance) &&
+            isNumber(this._instance.config.capture_performance.__web_vitals_max_value)
+                ? this._instance.config.capture_performance.__web_vitals_max_value
                 : FIFTEEN_MINUTES_IN_MILLIS
         // you can set to 0 to disable the check or any value over ten seconds
         // 1 milli to 1 minute will be set to 15 minutes, cos that would be a silly low maximum
@@ -77,10 +76,10 @@ export class WebVitalsAutocapture {
         }
 
         // Otherwise, check config
-        const clientConfig = isObject(this._perfConfig)
-            ? this._perfConfig.web_vitals
-            : isBoolean(this._perfConfig)
-              ? this._perfConfig
+        const clientConfig = isObject(this._instance.config.capture_performance)
+            ? this._instance.config.capture_performance.web_vitals
+            : isBoolean(this._instance.config.capture_performance)
+              ? this._instance.config.capture_performance
               : undefined
         return isBoolean(clientConfig) ? clientConfig : this._enabledServerSide
     }
@@ -149,7 +148,7 @@ export class WebVitalsAutocapture {
         const customPersonalDataProperties = this._instance.config.custom_personal_data_properties
 
         const paramsToMask = maskPersonalDataProperties
-            ? [...PERSONAL_DATA_CAMPAIGN_PARAMS, ...(customPersonalDataProperties || [])]
+            ? extendArray([], PERSONAL_DATA_CAMPAIGN_PARAMS, customPersonalDataProperties || [])
             : []
 
         return maskQueryParams(href, paramsToMask, MASKED)
@@ -177,12 +176,6 @@ export class WebVitalsAutocapture {
     }
 
     private _addToBuffer = (metric: any) => {
-        const sessionIds = this._instance.sessionManager?.checkAndGetSessionAndWindowId(true)
-        if (isUndefined(sessionIds)) {
-            logger.error('Could not read session ID. Dropping metrics!')
-            return
-        }
-
         this._buffer = this._buffer || { url: undefined, metrics: [], firstMetricTimestamp: undefined }
 
         const $currentUrl = this._currentURL()
@@ -230,13 +223,18 @@ export class WebVitalsAutocapture {
             metric.attribution.interactionTargetElement = undefined
         }
 
-        this._buffer.metrics.push({
+        const sessionIds = this._instance.sessionManager?.checkAndGetSessionAndWindowId(true)
+        const bufferedMetric: Record<string, unknown> = {
             ...metric,
             $current_url: $currentUrl,
-            $session_id: sessionIds.sessionId,
-            $window_id: sessionIds.windowId,
             timestamp: Date.now(),
-        })
+        }
+        if (!isUndefined(sessionIds)) {
+            bufferedMetric.$session_id = sessionIds.sessionId
+            bufferedMetric.$window_id = sessionIds.windowId
+        }
+
+        this._buffer.metrics.push(bufferedMetric)
 
         if (this._buffer.metrics.length === this.allowedMetrics.length) {
             // we have all allowed metrics
diff --git a/packages/types/src/posthog-config.ts b/packages/types/src/posthog-config.ts
@@ -151,6 +151,10 @@ export interface PerformanceCaptureConfig {
 
     /**
      * Use chrome's web vitals library to wrap fetch and capture web vitals
+     *
+     * When `cookieless_mode` is active, there is no client-side SessionIdManager; vitals are still
+     * captured. Nested `$web_vitals_*_event` payloads omit `$session_id` / `$window_id`; PostHog ingestion assigns
+     * `$session_id` server-side for cookieless traffic when project cookieless settings are enabled (same as other events).
      */
     web_vitals?: boolean
 
@@ -1561,6 +1565,10 @@ export interface PostHogConfig {
     /**
      * Enables cookieless mode. In this mode, PostHog will not set any cookies, or use session or local storage. User
      * identity is handled by generating a privacy-preserving hash on PostHog's servers.
+     *
+     * Web Vitals (`capture_performance.web_vitals`) are supported: metrics are sent without client session IDs;
+     * ingestion assigns `$session_id` when cookieless mode is enabled for the project.
+     *
      * - 'always' - enable cookieless mode immediately on startup, use this if you do not intend to show a cookie banner
      * - 'on_reject' - enable cookieless mode only if the user rejects cookies, use this if you want to show a cookie banner. If the user accepts cookies, cookieless mode will not be used, and PostHog will use cookies and local storage as usual.
      *
