feat: start session recording on url trigger

src/constants.ts

@@ -24,6 +24,7 @@ export const SESSION_RECORDING_SAMPLE_RATE = '$replay_sample_rate'
 export const SESSION_RECORDING_MINIMUM_DURATION = '$replay_minimum_duration'
 export const SESSION_ID = '$sesid'
 export const SESSION_RECORDING_IS_SAMPLED = '$session_is_sampled'
+export const SESSION_RECORDING_URL_TRIGGER_ACTIVATED = '$session_recording_url_trigger_activated'
 export const ENABLED_FEATURE_FLAGS = '$enabled_feature_flags'
 export const PERSISTENCE_EARLY_ACCESS_FEATURES = '$early_access_features'
 export const STORED_PERSON_PROPERTIES_KEY = '$stored_person_properties'

src/extensions/replay/sessionrecording.ts

@@ -6,6 +6,7 @@ import {
     SESSION_RECORDING_MINIMUM_DURATION,
     SESSION_RECORDING_NETWORK_PAYLOAD_CAPTURE,
     SESSION_RECORDING_SAMPLE_RATE,
+    SESSION_RECORDING_URL_TRIGGER_ACTIVATED,
 } from '../../constants'
 import {
     estimateSize,
@@ -16,7 +17,14 @@ import {
     truncateLargeConsoleLogs,
 } from './sessionrecording-utils'
 import { PostHog } from '../../posthog-core'
-import { DecideResponse, FlagVariant, NetworkRecordOptions, NetworkRequest, Properties } from '../../types'
+import {
+    DecideResponse,
+    FlagVariant,
+    NetworkRecordOptions,
+    NetworkRequest,
+    Properties,
+    SessionRecordingUrlTrigger,
+} from '../../types'
 import {
     customEvent,
     EventType,
@@ -36,6 +44,7 @@ import { gzipSync, strFromU8, strToU8 } from 'fflate'
 
 const BASE_ENDPOINT = '/s/'
 
+const ONE_MINUTE = 1000 * 60
 const FIVE_MINUTES = 1000 * 60 * 5
 const TWO_SECONDS = 2000
 export const RECORDING_IDLE_THRESHOLD_MS = FIVE_MINUTES
@@ -60,6 +69,9 @@ const ACTIVE_SOURCES = [
     IncrementalSource.Drag,
 ]
 
+const TRIGGER_STATUSES = ['activated', 'pending', 'disabled'] as const
+type TriggerStatus = typeof TRIGGER_STATUSES[number]
+
 /**
  * Session recording starts in buffering mode while waiting for decide response
  * Once the response is received it might be disabled, active or sampled
@@ -228,6 +240,8 @@ export class SessionRecording {
     // then we can manually track href changes
     private _lastHref?: string
 
+    private _urlTriggers: SessionRecordingUrlTrigger[] = []
+
     // Util to help developers working on this feature manually override
     _forceAllowLocalhostNetworkCapture = false
 
@@ -253,7 +267,11 @@ export class SessionRecording {
     }
 
     private get fullSnapshotIntervalMillis(): number {
-        return this.instance.config.session_recording?.full_snapshot_interval_millis || FIVE_MINUTES
+        if (this.urlTriggerStatus === 'pending') {
+            return ONE_MINUTE
+        }
+
+        return this.instance.config.session_recording?.full_snapshot_interval_millis ?? FIVE_MINUTES
     }
 
     private get isSampled(): boolean | null {
@@ -343,13 +361,37 @@ export class SessionRecording {
             return 'buffering'
         }
 
+        if (this.urlTriggerStatus === 'pending') {
+            return 'buffering'
+        }
+
         if (isBoolean(this.isSampled)) {
             return this.isSampled ? 'sampled' : 'disabled'
         } else {
             return 'active'
         }
     }
 
+    private get urlTriggerStatus(): 'activated' | 'pending' | 'disabled' {
+        if (this.receivedDecide && this._urlTriggers.length === 0) {
+            return 'disabled'
+        }
+
+        const currentValue = this.instance?.get_property(SESSION_RECORDING_URL_TRIGGER_ACTIVATED)
+
+        if (TRIGGER_STATUSES.includes(currentValue)) {
+            return currentValue as TriggerStatus
+        }
+
+        return 'pending'
+    }
+
+    private set urlTriggerStatus(status: TriggerStatus) {
+        this.instance?.persistence?.register({
+            [SESSION_RECORDING_URL_TRIGGER_ACTIVATED]: status,
+        })
+    }
+
     constructor(private readonly instance: PostHog) {
         this._captureStarted = false
         this._endpoint = BASE_ENDPOINT
@@ -544,6 +586,10 @@ export class SessionRecording {
             })
         }
 
+        if (response.sessionRecording?.urlTriggers) {
+            this._urlTriggers = response.sessionRecording.urlTriggers
+        }
+
         this.receivedDecide = true
         this.startIfEnabledOrStop()
     }
@@ -909,11 +955,19 @@ export class SessionRecording {
             this._pageViewFallBack()
         }
 
+        // Check if the URL matches any trigger patterns
+        this._checkUrlTrigger()
+
         // we're processing a full snapshot, so we should reset the timer
         if (rawEvent.type === EventType.FullSnapshot) {
             this._scheduleFullSnapshot()
         }
 
+        // Clear the buffer if waiting for a trigger, and only keep data from after the current full snapshot
+        if (rawEvent.type === EventType.FullSnapshot && this.urlTriggerStatus === 'pending') {
+            this.clearBuffer()
+        }
+
         const throttledEvent = this.mutationRateLimiter
             ? this.mutationRateLimiter.throttleMutations(rawEvent)
             : rawEvent
@@ -1090,6 +1144,36 @@ export class SessionRecording {
         })
     }
 
+    private _checkUrlTrigger() {
+        if (typeof window === 'undefined' || !window.location.href) {
+            return
+        }
+
+        const url = window.location.href
+
+        if (
+            this._urlTriggers.some((trigger) => {
+                switch (trigger.matching) {
+                    case 'regex':
+                        return new RegExp(trigger.url).test(url)
+                    default:
+                        return false
+                }
+            })
+        ) {
+            this._activateUrlTrigger()
+        }
+    }
+
+    private _activateUrlTrigger() {
+        if (this.urlTriggerStatus === 'pending') {
+            this.urlTriggerStatus = 'activated'
+            this._tryAddCustomEvent('url trigger activated', {})
+            this._flushBuffer()
+            logger.info(LOGGER_PREFIX + ' recording triggered by URL pattern match')
+        }
+    }
+
     /**
      * this ignores the linked flag config and causes capture to start
      * (if recording would have started had the flag been received i.e. it does not override other config).

src/types.ts

@@ -390,6 +390,7 @@ export interface DecideResponse {
         canvasQuality?: string | null
         linkedFlag?: string | FlagVariant | null
         networkPayloadCapture?: Pick<NetworkRecordOptions, 'recordBody' | 'recordHeaders'>
+        urlTriggers?: SessionRecordingUrlTrigger[]
     }
     surveys?: boolean
     toolbarParams: ToolbarParams
@@ -594,3 +595,8 @@ export interface ErrorConversions {
     errorToProperties: (args: ErrorEventArgs) => ErrorProperties
     unhandledRejectionToProperties: (args: [ev: PromiseRejectionEvent]) => ErrorProperties
 }
+
+export interface SessionRecordingUrlTrigger {
+    url: string
+    matching: 'regex'
+}