fix: web vitals delayed capture

src/__tests__/extensions/web-vitals.test.ts

@@ -1,9 +1,9 @@
 import { createPosthogInstance } from '../helpers/posthog-instance'
 import { uuidv7 } from '../../uuidv7'
 import { PostHog } from '../../posthog-core'
-import { DecideResponse, SupportedWebVitalsMetrics } from '../../types'
+import { DecideResponse, PerformanceCaptureConfig, SupportedWebVitalsMetrics } from '../../types'
 import { assignableWindow } from '../../utils/globals'
-import { FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS, FIFTEEN_MINUTES_IN_MILLIS } from '../../extensions/web-vitals'
+import { DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS, FIFTEEN_MINUTES_IN_MILLIS } from '../../extensions/web-vitals'
 
 jest.mock('../../utils/logger')
 jest.useFakeTimers()
@@ -134,12 +134,12 @@ describe('web vitals', () => {
  ])
  })
 
- it('should emit after 8 seconds even when only 1 to 3 metrics captured', async () => {
+ it('should emit after 5 seconds even when only 1 to 3 metrics captured', async () => {
  onCLSCallback?.({ name: 'CLS', value: 123.45, extra: 'property' })
 
  expect(onCapture).toBeCalledTimes(0)
 
- jest.advanceTimersByTime(FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
+ jest.advanceTimersByTime(DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
 
  // for some reason advancing the timer emits a $pageview event as well 🤷
  // expect(onCapture).toBeCalledTimes(2)
@@ -155,12 +155,32 @@ describe('web vitals', () => {
  ])
  })
 
+ it('should emit after configured timeout even when only 1 to 3 metrics captured', async () => {
+ ;(posthog.config.capture_performance as PerformanceCaptureConfig).web_vitals_delayed_flush_ms = 1000
+ onCLSCallback?.({ name: 'CLS', value: 123.45, extra: 'property' })
+
+ expect(onCapture).toBeCalledTimes(0)
+
+ jest.advanceTimersByTime(1000 + 1)
+
+ expect(onCapture.mock.lastCall).toMatchObject([
+ '$web_vitals',
+ {
+ event: '$web_vitals',
+ properties: {
+ $web_vitals_CLS_event: expectedEmittedWebVitals('CLS'),
+ $web_vitals_CLS_value: 123.45,
+ },
+ },
+ ])
+ })
+
  it('should ignore a ridiculous value', async () => {
  onCLSCallback?.({ name: 'CLS', value: FIFTEEN_MINUTES_IN_MILLIS, extra: 'property' })
 
  expect(onCapture).toBeCalledTimes(0)
 
- jest.advanceTimersByTime(FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
+ jest.advanceTimersByTime(DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
 
  expect(onCapture.mock.calls).toEqual([])
  })
@@ -171,7 +191,7 @@ describe('web vitals', () => {
 
  expect(onCapture).toBeCalledTimes(0)
 
- jest.advanceTimersByTime(FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
+ jest.advanceTimersByTime(DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS + 1)
 
  expect(onCapture).toBeCalledTimes(1)
  })

src/extensions/web-vitals/index.ts

@@ -7,7 +7,7 @@ import { assignableWindow, window } from '../../utils/globals'
 
 type WebVitalsMetricCallback = (metric: any) => void
 
-export const FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS = 8000
+export const DEFAULT_FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS = 5000
 const ONE_MINUTE_IN_MILLIS = 60 * 1000
 export const FIFTEEN_MINUTES_IN_MILLIS = 15 * ONE_MINUTE_IN_MILLIS
 
@@ -38,6 +38,13 @@ export class WebVitalsAutocapture {
  : this.instance.persistence?.props[WEB_VITALS_ALLOWED_METRICS] || ['CLS', 'FCP', 'INP', 'LCP']
  }
 
+ public get flushToCaptureTimeoutMs(): number {
+ 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 _maxAllowedValue(): number {
  const configured =
  isObject(this.instance.config.capture_performance) &&
@@ -163,7 +170,7 @@ export class WebVitalsAutocapture {
  // poor performance is >4s, we wait twice that time to send
  // this is in case we haven't received all metrics
  // we'll at least gather some
- this._delayedFlushTimer = setTimeout(this._flushToCapture, FLUSH_TO_CAPTURE_TIMEOUT_MILLISECONDS)
+ this._delayedFlushTimer = setTimeout(this._flushToCapture, this.flushToCaptureTimeoutMs)
  }
 
  if (isUndefined(this.buffer.url)) {

src/types.ts

@@ -114,6 +114,12 @@ export interface PerformanceCaptureConfig {
  * NB setting this does not override whether the capture is enabled
  */
  web_vitals_allowed_metrics?: SupportedWebVitalsMetrics[]
+ /**
+ * we delay flushing web vitals metrics to reduce the number of events we send
+ * this is the maximum time we will wait before sending the metrics
+ * if not set it defaults to 5 seconds
+ */
+ web_vitals_delayed_flush_ms?: number
 }
 
 export interface HeatmapConfig {