feat: allow triggering sessions when events occur

src/constants.ts

@@ -25,8 +25,8 @@ 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 = '$session_recording_url_trigger_activated_session'
-export const SESSION_RECORDING_URL_TRIGGER_STATUS = '$session_recording_url_trigger_status'
+export const SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION = '$session_recording_trigger_activated_session'
+export const SESSION_RECORDING_TRIGGER_STATUS = '$session_recording_trigger_status'
 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

@@ -2,12 +2,12 @@ import {
     CONSOLE_LOG_RECORDING_ENABLED_SERVER_SIDE,
     SESSION_RECORDING_CANVAS_RECORDING,
     SESSION_RECORDING_ENABLED_SERVER_SIDE,
+    SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION,
+    SESSION_RECORDING_TRIGGER_STATUS,
     SESSION_RECORDING_IS_SAMPLED,
     SESSION_RECORDING_MINIMUM_DURATION,
     SESSION_RECORDING_NETWORK_PAYLOAD_CAPTURE,
     SESSION_RECORDING_SAMPLE_RATE,
-    SESSION_RECORDING_URL_TRIGGER_ACTIVATED_SESSION,
-    SESSION_RECORDING_URL_TRIGGER_STATUS,
 } from '../../constants'
 import {
     estimateSize,
@@ -51,6 +51,8 @@ type SessionStartReason =
     | 'linked_flag_override'
     | 'sampling'
     | 'session_id_changed'
+    | 'url_trigger_match'
+    | 'event_trigger_match'
 
 const BASE_ENDPOINT = '/s/'
 
@@ -266,6 +268,9 @@ export class SessionRecording {
 
     private _urlBlocked: boolean = false
 
+    private _eventTriggers: string[] = []
+    private _removeEventTriggerCaptureHook: (() => void) | undefined = undefined
+
     // Util to help developers working on this feature manually override
     _forceAllowLocalhostNetworkCapture = false
 
@@ -291,7 +296,7 @@ export class SessionRecording {
     }
 
     private get fullSnapshotIntervalMillis(): number {
-        if (this.urlTriggerStatus === 'trigger_pending') {
+        if (this.triggerStatus === 'trigger_pending') {
             return ONE_MINUTE
         }
 
@@ -389,7 +394,7 @@ export class SessionRecording {
             return 'buffering'
         }
 
-        if (this.urlTriggerStatus === 'trigger_pending') {
+        if (this.triggerStatus === 'trigger_pending') {
             return 'buffering'
         }
 
@@ -404,17 +409,17 @@ export class SessionRecording {
         }
     }
 
-    private get urlTriggerStatus(): TriggerStatus {
-        if (this._urlTriggers.length === 0) {
+    private get triggerStatus(): TriggerStatus {
+        if (this._urlTriggers.length === 0 && this._eventTriggers.length === 0) {
             return 'trigger_disabled'
         }
 
-        const currentStatus = this.instance?.get_property(SESSION_RECORDING_URL_TRIGGER_STATUS)
-        const currentTriggerSession = this.instance?.get_property(SESSION_RECORDING_URL_TRIGGER_ACTIVATED_SESSION)
+        const currentStatus = this.instance?.get_property(SESSION_RECORDING_TRIGGER_STATUS)
+        const currentTriggerSession = this.instance?.get_property(SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION)
 
         if (currentTriggerSession !== this.sessionId) {
-            this.instance?.persistence?.unregister(SESSION_RECORDING_URL_TRIGGER_ACTIVATED_SESSION)
-            this.instance?.persistence?.unregister(SESSION_RECORDING_URL_TRIGGER_STATUS)
+            this.instance?.persistence?.unregister(SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION)
+            this.instance?.persistence?.unregister(SESSION_RECORDING_TRIGGER_STATUS)
             return 'trigger_pending'
         }
 
@@ -425,10 +430,10 @@ export class SessionRecording {
         return 'trigger_pending'
     }
 
-    private set urlTriggerStatus(status: TriggerStatus) {
+    private set triggerStatus(status: TriggerStatus) {
         this.instance?.persistence?.register({
-            [SESSION_RECORDING_URL_TRIGGER_ACTIVATED_SESSION]: this.sessionId,
-            [SESSION_RECORDING_URL_TRIGGER_STATUS]: status,
+            [SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION]: this.sessionId,
+            [SESSION_RECORDING_TRIGGER_STATUS]: status,
         })
     }
 
@@ -491,6 +496,8 @@ export class SessionRecording {
             // so we call this here _and_ in the decide response
             this._setupSampling()
 
+            this._addEventTriggerListener()
+
             if (isNullish(this._removePageViewCaptureHook)) {
                 // :TRICKY: rrweb does not capture navigation within SPA-s, so hook into our $pageview events to get access to all events.
                 //   Dropping the initial event is fine (it's always captured by rrweb).
@@ -516,8 +523,8 @@ export class SessionRecording {
                     if (changeReason) {
                         this._tryAddCustomEvent('$session_id_change', { sessionId, windowId, changeReason })
 
-                        this.instance?.persistence?.unregister(SESSION_RECORDING_URL_TRIGGER_ACTIVATED_SESSION)
-                        this.instance?.persistence?.unregister(SESSION_RECORDING_URL_TRIGGER_STATUS)
+                        this.instance?.persistence?.unregister(SESSION_RECORDING_TRIGGER_ACTIVATED_SESSION)
+                        this.instance?.persistence?.unregister(SESSION_RECORDING_TRIGGER_STATUS)
                     }
                 })
             }
@@ -644,6 +651,10 @@ export class SessionRecording {
             this._urlBlocklist = response.sessionRecording.urlBlocklist
         }
 
+        if (response.sessionRecording?.eventTriggers) {
+            this._eventTriggers = response.sessionRecording.eventTriggers
+        }
+
         this.receivedDecide = true
         this.startIfEnabledOrStop()
     }
@@ -1012,7 +1023,7 @@ export class SessionRecording {
         }
 
         // Check if the URL matches any trigger patterns
-        this._checkTriggerConditions()
+        this._checkUrlTriggerConditions()
 
         if (this.status === 'paused' && !isRecordingPausedEvent(rawEvent)) {
             return
@@ -1024,7 +1035,7 @@ export class SessionRecording {
         }
 
         // 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 === 'trigger_pending') {
+        if (rawEvent.type === EventType.FullSnapshot && this.triggerStatus === 'trigger_pending') {
             this.clearBuffer()
         }
 
@@ -1205,7 +1216,7 @@ export class SessionRecording {
         })
     }
 
-    private _checkTriggerConditions() {
+    private _checkUrlTriggerConditions() {
         if (typeof window === 'undefined' || !window.location.href) {
             return
         }
@@ -1222,16 +1233,17 @@ export class SessionRecording {
         }
 
         if (sessionRecordingUrlTriggerMatches(url, this._urlTriggers)) {
-            this._activateUrlTrigger()
+            this._activateTrigger('url')
         }
     }
 
-    private _activateUrlTrigger() {
-        if (this.urlTriggerStatus === 'trigger_pending') {
-            this.urlTriggerStatus = 'trigger_activated'
-            this._tryAddCustomEvent('url trigger activated', {})
+    private _activateTrigger(triggerType: 'url' | 'event') {
+        if (this.triggerStatus === 'trigger_pending') {
+            this.triggerStatus = 'trigger_activated'
+            this._tryAddCustomEvent(`${triggerType} trigger activated`, {})
+            this._reportStarted(triggerType === 'url' ? 'url_trigger_match' : 'event_trigger_match')
             this._flushBuffer()
-            logger.info(LOGGER_PREFIX + ' recording triggered by URL pattern match')
+            logger.info(LOGGER_PREFIX + ` recording triggered by ${triggerType}`)
         }
     }
 
@@ -1270,6 +1282,24 @@ export class SessionRecording {
         logger.info(LOGGER_PREFIX + ' recording resumed')
     }
 
+    private _addEventTriggerListener() {
+        if (this._eventTriggers.length === 0 || !isNullish(this._removeEventTriggerCaptureHook)) {
+            return
+        }
+
+        this._removeEventTriggerCaptureHook = this.instance._addCaptureHook((eventName) => {
+            // If anything could go wrong here it has the potential to block the main loop,
+            // so we catch all errors.
+            try {
+                if (this._eventTriggers.includes(eventName)) {
+                    this._activateTrigger('event')
+                }
+            } catch (e) {
+                logger.error('Could not activate event trigger', e)
+            }
+        })
+    }
+
     /**
      * 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

@@ -452,6 +452,7 @@ export interface DecideResponse {
         networkPayloadCapture?: Pick<NetworkRecordOptions, 'recordBody' | 'recordHeaders'>
         urlTriggers?: SessionRecordingUrlTrigger[]
         urlBlocklist?: SessionRecordingUrlTrigger[]
+        eventTriggers?: string[]
     }
     surveys?: boolean
     toolbarParams: ToolbarParams