feat(session replay): correct timing of replay capture, and use targeting config or sampling config (#841)

Author: Kelly Wallach

packages/plugin-session-replay-browser/src/session-replay.ts

@@ -48,7 +48,7 @@ class SessionReplayEnrichmentPlugin implements EnrichmentPlugin {
       if (event.event_type === SpecialEventType.IDENTIFY) {
         userProperties = parseUserProperties(event);
       }
-      await sessionReplay.evaluateTargetingAndRecord({ event, userProperties });
+      await sessionReplay.evaluateTargetingAndCapture({ event, userProperties });
       const sessionRecordingProperties = sessionReplay.getSessionReplayProperties();
       event.event_properties = {
         ...event.event_properties,

packages/plugin-session-replay-browser/test/session-replay.test.ts

@@ -20,7 +20,7 @@ type MockedLogger = jest.Mocked<Logger>;
 type MockedBrowserClient = jest.Mocked<BrowserClient>;
 
 describe('SessionReplayPlugin', () => {
-  const { init, setSessionId, getSessionReplayProperties, evaluateTargetingAndRecord, flush, shutdown, getSessionId } =
+  const { init, setSessionId, getSessionReplayProperties, evaluateTargetingAndCapture, flush, shutdown, getSessionId } =
     sessionReplayBrowser as MockedSessionReplayBrowser;
   const mockLoggerProvider: MockedLogger = {
     error: jest.fn(),
@@ -334,7 +334,7 @@ describe('SessionReplayPlugin', () => {
       await sessionReplayEnrichmentPlugin.setup(mockConfig);
       await sessionReplayEnrichmentPlugin.execute(event);
 
-      expect(evaluateTargetingAndRecord).toHaveBeenCalledWith({
+      expect(evaluateTargetingAndCapture).toHaveBeenCalledWith({
         event: event,
         userProperties: undefined,
       });
@@ -360,7 +360,7 @@ describe('SessionReplayPlugin', () => {
       await sessionReplayEnrichmentPlugin.setup(mockConfig);
       await sessionReplayEnrichmentPlugin.execute(event);
 
-      expect(evaluateTargetingAndRecord).toHaveBeenCalledWith({
+      expect(evaluateTargetingAndCapture).toHaveBeenCalledWith({
         event: event,
         userProperties: {
           plan_id: 'free',

packages/session-replay-browser/README.md

@@ -50,7 +50,7 @@ sessionReplay.init(API_KEY, {
 ### 3. Evaluate targeting (optional)
 Any event that occurs within the span of a session replay must be passed to the SDK to evaluate against targeting conditions. This should be done *before* step 4, getting the event properties. If you are not using the targeting condition logic provided via the Amplitude UI, this step is not required.
 ```typescript
-const sessionTargetingMatch = sessionReplay.evaluateTargetingAndRecord({ event: {
+const sessionTargetingMatch = sessionReplay.evaluateTargetingAndCapture({ event: {
   event_type: EVENT_NAME,
   time: EVENT_TIMESTAMP,
   event_properties: eventProperties

packages/session-replay-browser/package.json

@@ -43,7 +43,7 @@
     "@amplitude/analytics-remote-config": "^0.3.4",
     "@amplitude/analytics-types": ">=1 <3",
     "@amplitude/rrweb": "2.0.0-alpha.19",
-    "@amplitude/targeting": "0.1.1",
+    "@amplitude/targeting": "0.2.0",
     "idb": "^8.0.0",
     "tslib": "^2.4.1"
   },

packages/session-replay-browser/src/index.ts

@@ -3,7 +3,7 @@ export const {
   init,
   setSessionId,
   getSessionId,
-  evaluateTargetingAndRecord,
+  evaluateTargetingAndCapture,
   getSessionReplayProperties,
   flush,
   shutdown,

packages/session-replay-browser/src/session-replay-factory.ts

@@ -17,8 +17,8 @@ const createInstance: () => AmplitudeSessionReplay = () => {
   const sessionReplay = new SessionReplay();
   return {
     init: debugWrapper(sessionReplay.init.bind(sessionReplay), 'init', getLogConfig(sessionReplay)),
-    evaluateTargetingAndRecord: debugWrapper(
-      sessionReplay.evaluateTargetingAndRecord.bind(sessionReplay),
+    evaluateTargetingAndCapture: debugWrapper(
+      sessionReplay.evaluateTargetingAndCapture.bind(sessionReplay),
       'evaluateTargetingAndRecord',
       getLogConfig(sessionReplay),
     ),

packages/session-replay-browser/src/session-replay.ts

@@ -128,14 +128,17 @@ export class SessionReplay implements AmplitudeSessionReplay {
 
     this.teardownEventListeners(false);
 
-    await this.evaluateTargetingAndRecord({ userProperties: options.userProperties });
+    this.stopRecordingEvents();
+    await this.evaluateTargetingAndCapture({ userProperties: options.userProperties });
   }
 
   setSessionId(sessionId: number, deviceId?: string, options?: { userProperties?: { [key: string]: any } }) {
     return returnWrapper(this.asyncSetSessionId(sessionId, deviceId, options));
   }
 
   async asyncSetSessionId(sessionId: number, deviceId?: string, options?: { userProperties?: { [key: string]: any } }) {
+    this.stopRecordingEvents();
+
     const previousSessionId = this.identifiers && this.identifiers.sessionId;
     if (previousSessionId) {
       this.sendEvents(previousSessionId);
@@ -152,7 +155,7 @@ export class SessionReplay implements AmplitudeSessionReplay {
     if (this.joinedConfigGenerator && previousSessionId) {
       this.config = await this.joinedConfigGenerator.generateJoinedConfig(this.identifiers.sessionId);
     }
-    await this.evaluateTargetingAndRecord({ userProperties: options?.userProperties });
+    await this.evaluateTargetingAndCapture({ userProperties: options?.userProperties });
   }
 
   getSessionReplayDebugPropertyValue() {
@@ -171,7 +174,7 @@ export class SessionReplay implements AmplitudeSessionReplay {
       return {};
     }
 
-    const shouldRecord = this.getShouldRecord();
+    const shouldRecord = this.getShouldCapture();
 
     if (shouldRecord) {
       const eventProperties: { [key: string]: string | null } = {
@@ -193,9 +196,8 @@ export class SessionReplay implements AmplitudeSessionReplay {
   focusListener = () => {
     // Restart recording on focus to ensure that when user
     // switches tabs, we take a full snapshot
-    if (this.sessionTargetingMatch) {
-      this.recordEvents();
-    }
+    this.stopRecordingEvents();
+    this.captureEvents();
   };
 
   /**
@@ -209,44 +211,35 @@ export class SessionReplay implements AmplitudeSessionReplay {
     });
   };
 
-  evaluateTargetingAndRecord = async (targetingParams?: Pick<TargetingParameters, 'event' | 'userProperties'>) => {
+  evaluateTargetingAndCapture = async (targetingParams?: Pick<TargetingParameters, 'event' | 'userProperties'>) => {
     if (!this.identifiers || !this.identifiers.sessionId || !this.config) {
-      if (!this.identifiers?.sessionId) {
-        this.loggerProvider.warn('Session ID has not been set, cannot evaluate targeting for Session Replay.');
+      if (this.identifiers && !this.identifiers.sessionId) {
+        this.loggerProvider.log('Session ID has not been set yet, cannot evaluate targeting for Session Replay.');
       } else {
         this.loggerProvider.warn('Session replay init has not been called, cannot evaluate targeting.');
       }
-      return false;
-    }
-    // Return early if a targeting match has already been made
-    if (this.sessionTargetingMatch) {
-      if (!this.recordCancelCallback) {
-        this.loggerProvider.log('Session replay capture beginning due to targeting match.');
-        this.recordEvents();
-      }
-      return this.sessionTargetingMatch;
-    }
-
-    let eventForTargeting = targetingParams?.event;
-    if (
-      eventForTargeting &&
-      Object.values(SpecialEventType).includes(eventForTargeting.event_type as SpecialEventType)
-    ) {
-      eventForTargeting = undefined;
+      return;
     }
 
-    this.sessionTargetingMatch = await evaluateTargetingAndStore({
-      sessionId: this.identifiers.sessionId,
-      config: this.config,
-      targetingParams: { userProperties: targetingParams?.userProperties, event: eventForTargeting },
-    });
+    if (this.config.targetingConfig && !this.sessionTargetingMatch) {
+      let eventForTargeting = targetingParams?.event;
+      if (
+        eventForTargeting &&
+        Object.values(SpecialEventType).includes(eventForTargeting.event_type as SpecialEventType)
+      ) {
+        eventForTargeting = undefined;
+      }
 
-    if (this.sessionTargetingMatch) {
-      this.loggerProvider.log('Session replay capture beginning due to targeting match.');
-      this.recordEvents();
+      this.sessionTargetingMatch = await evaluateTargetingAndStore({
+        sessionId: this.identifiers.sessionId,
+        targetingConfig: this.config.targetingConfig,
+        loggerProvider: this.loggerProvider,
+        apiKey: this.config.apiKey,
+        targetingParams: { userProperties: targetingParams?.userProperties, event: eventForTargeting },
+      });
     }
 
-    return this.sessionTargetingMatch;
+    this.captureEvents();
   };
 
   sendEvents(sessionId?: number) {
@@ -268,9 +261,9 @@ export class SessionReplay implements AmplitudeSessionReplay {
     return identityStoreOptOut !== undefined ? identityStoreOptOut : this.config?.optOut;
   }
 
-  getShouldRecord() {
+  getShouldCapture() {
     if (!this.identifiers || !this.config || !this.identifiers.sessionId) {
-      this.loggerProvider.warn(`Session is not being recorded due to lack of config, please call sessionReplay.init.`);
+      this.loggerProvider.warn(`Session is not being captured due to lack of config, please call sessionReplay.init.`);
       return false;
     }
     if (!this.config.captureEnabled) {
@@ -281,14 +274,35 @@ export class SessionReplay implements AmplitudeSessionReplay {
     }
 
     if (this.shouldOptOut()) {
-      this.loggerProvider.log(`Opting session ${this.identifiers.sessionId} out of recording due to optOut config.`);
+      this.loggerProvider.log(
+        `Opting session ${this.identifiers.sessionId} out of replay capture due to optOut config.`,
+      );
       return false;
     }
 
-    const isInSample = isSessionInSample(this.identifiers.sessionId, this.config.sampleRate);
-    if (!isInSample) {
-      this.loggerProvider.log(`Opting session ${this.identifiers.sessionId} out of recording due to sample rate.`);
-      return false;
+    // If targetingConfig exists, we'll use the sessionTargetingMatch to determine whether to record
+    // Otherwise, we'll evaluate the session against the overall sample rate
+    if (this.config.targetingConfig) {
+      if (!this.sessionTargetingMatch) {
+        this.loggerProvider.log(
+          `Not capturing replays for session ${this.identifiers.sessionId} due to not matching targeting conditions.`,
+        );
+        return false;
+      }
+      this.loggerProvider.log(
+        `Capturing replays for session ${this.identifiers.sessionId} due to matching targeting conditions.`,
+      );
+    } else {
+      const isInSample = isSessionInSample(this.identifiers.sessionId, this.config.sampleRate);
+      if (!isInSample) {
+        this.loggerProvider.log(
+          `Opting session ${this.identifiers.sessionId} out of replay capture due to sample rate.`,
+        );
+        return false;
+      }
+      this.loggerProvider.log(
+        `Capturing replays for session  ${this.identifiers.sessionId} due to inclusion in sample rate.`,
+      );
     }
 
     return true;
@@ -318,20 +332,25 @@ export class SessionReplay implements AmplitudeSessionReplay {
     return maskSelector as unknown as string;
   }
 
-  recordEvents() {
-    const shouldRecord = this.getShouldRecord();
-    const sessionId = this.identifiers?.sessionId;
+  captureEvents() {
+    if (this.recordCancelCallback) {
+      this.loggerProvider.debug('captureEvents method fired - Session Replay capture already in progress.');
+      return;
+    }
+
+    const shouldRecord = this.getShouldCapture();
+    const sessionId = this.identifiers && this.identifiers.sessionId;
     if (!shouldRecord || !sessionId || !this.config) {
       return;
     }
-    this.stopRecordingEvents();
+
     const privacyConfig = this.config.privacyConfig;
 
     this.loggerProvider.log('Session Replay capture beginning.');
     this.recordCancelCallback = record({
       emit: (event) => {
         if (this.shouldOptOut()) {
-          this.loggerProvider.log(`Opting session ${sessionId} out of recording due to optOut config.`);
+          this.loggerProvider.log(`Opting session ${sessionId} out of replay capture due to optOut config.`);
           this.stopRecordingEvents();
           this.sendEvents();
           return;

packages/session-replay-browser/src/targeting/targeting-manager.ts

@@ -1,25 +1,30 @@
 import { TargetingParameters, evaluateTargeting as evaluateTargetingPackage } from '@amplitude/targeting';
-import { SessionReplayJoinedConfig } from 'src/config/types';
+import { TargetingConfig } from '../config/types';
+import { Logger } from '@amplitude/analytics-types';
 import { targetingIDBStore } from './targeting-idb-store';
 
 export const evaluateTargetingAndStore = async ({
   sessionId,
-  config,
+  targetingConfig,
+  loggerProvider,
+  apiKey,
   targetingParams,
 }: {
   sessionId: number;
-  config: SessionReplayJoinedConfig;
+  targetingConfig: TargetingConfig;
+  loggerProvider: Logger;
+  apiKey: string;
   targetingParams?: Pick<TargetingParameters, 'event' | 'userProperties'>;
 }) => {
   await targetingIDBStore.clearStoreOfOldSessions({
-    loggerProvider: config.loggerProvider,
-    apiKey: config.apiKey,
+    loggerProvider: loggerProvider,
+    apiKey: apiKey,
     currentSessionId: sessionId,
   });
 
   const idbTargetingMatch = await targetingIDBStore.getTargetingMatchForSession({
-    loggerProvider: config.loggerProvider,
-    apiKey: config.apiKey,
+    loggerProvider: loggerProvider,
+    apiKey: apiKey,
     sessionId: sessionId,
   });
   if (idbTargetingMatch === true) {
@@ -31,26 +36,26 @@ export const evaluateTargetingAndStore = async ({
   // so all users match targeting
   let sessionTargetingMatch = true;
   try {
-    if (config.targetingConfig && Object.keys(config.targetingConfig).length) {
-      const targetingResult = await evaluateTargetingPackage({
-        ...targetingParams,
-        flag: config.targetingConfig,
-        sessionId: sessionId,
-        apiKey: config.apiKey,
-        loggerProvider: config.loggerProvider,
-      });
-
+    const targetingResult = await evaluateTargetingPackage({
+      ...targetingParams,
+      flag: targetingConfig,
+      sessionId: sessionId,
+      apiKey: apiKey,
+      loggerProvider: loggerProvider,
+    });
+    if (targetingResult && targetingResult.sr_targeting_config) {
       sessionTargetingMatch = targetingResult.sr_targeting_config.key === 'on';
     }
+
     void targetingIDBStore.storeTargetingMatchForSession({
-      loggerProvider: config.loggerProvider,
-      apiKey: config.apiKey,
+      loggerProvider: loggerProvider,
+      apiKey: apiKey,
       sessionId: sessionId,
       targetingMatch: sessionTargetingMatch,
     });
   } catch (err: unknown) {
     const knownError = err as Error;
-    config.loggerProvider.warn(knownError.message);
+    loggerProvider.warn(knownError.message);
   }
   return sessionTargetingMatch;
 };

packages/session-replay-browser/src/typings/session-replay.ts

@@ -79,9 +79,9 @@ export interface AmplitudeSessionReplay {
   ) => AmplitudeReturn<void>;
   getSessionId: () => number | undefined;
   getSessionReplayProperties: () => { [key: string]: boolean | string | null };
-  evaluateTargetingAndRecord: (
+  evaluateTargetingAndCapture: (
     targetingParams?: Pick<TargetingParameters, 'event' | 'userProperties'>,
-  ) => Promise<boolean>;
+  ) => Promise<void>;
   flush: (useRetry: boolean) => Promise<void>;
   shutdown: () => void;
 }