feat(session replay): add ability to capture replays based on targeting via remote config

Author: Kelly Wallach

packages/plugin-session-replay-browser/CHANGELOG.md

@@ -23,16 +23,21 @@ All notable changes to this project will be documented in this file. See
 
 ## [1.6.18](https://github.com/amplitude/Amplitude-TypeScript/compare/@amplitude/[email protected]...@amplitude/[email protected]) (2024-08-13)
 
-**Note:** Version bump only for package @amplitude/plugin-session-replay-browser
-
-# Change Log
+### Bug Fixes
 
-All notable changes to this project will be documented in this file. See
-[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+- **session replay plugin:** remove unused if check
+  ([fc63646](https://github.com/amplitude/Amplitude-TypeScript/commit/fc6364683c416778b0609f20370454ee45437230))
+- **session replay:** rebase fixes
+  ([8386ede](https://github.com/amplitude/Amplitude-TypeScript/commit/8386ede0f8f61b71ed0b73d78967d465ed3567e9))
 
-## [1.6.17](https://github.com/amplitude/Amplitude-TypeScript/compare/@amplitude/[email protected]...@amplitude/[email protected]) (2024-08-12)
+### Features
 
-**Note:** Version bump only for package @amplitude/plugin-session-replay-browser
+- **session replay plugin:** support targeting by user properties
+  ([ba8e27d](https://github.com/amplitude/Amplitude-TypeScript/commit/ba8e27d070b2015afc846f7ef02b745cff485d76))
+- **session replay:** add ability to target by single event trigger
+  ([dab74f7](https://github.com/amplitude/Amplitude-TypeScript/commit/dab74f73dd5946ac99e517c57d97819acf3677f4))
+- **session replay:** update method names, and ensure targeting is independent from sampling
+  ([6d3a7be](https://github.com/amplitude/Amplitude-TypeScript/commit/6d3a7be4169e6e0e3bd8c7103895374daea107bd))
 
 # Change Log
 

packages/plugin-session-replay-browser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplitude/plugin-session-replay-browser",
-  "version": "1.6.20",
+  "version": "1.7.0-srtargeting.0",
   "description": "",
   "author": "Amplitude Inc",
   "homepage": "https://github.com/amplitude/Amplitude-TypeScript",
@@ -41,7 +41,7 @@
     "@amplitude/analytics-client-common": ">=1 <3",
     "@amplitude/analytics-core": ">=1 <3",
     "@amplitude/analytics-types": ">=1 <3",
-    "@amplitude/session-replay-browser": "^1.13.4",
+    "@amplitude/session-replay-browser": "^1.14.0-srtargeting.0",
     "idb-keyval": "^6.2.1",
     "tslib": "^2.4.1"
   },

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

@@ -0,0 +1,11 @@
+import { IdentifyOperation } from '@amplitude/analytics-types';
+
+export const PROPERTY_ADD_OPERATIONS = [
+  IdentifyOperation.SET,
+  IdentifyOperation.SET_ONCE,
+  IdentifyOperation.ADD,
+  IdentifyOperation.APPEND,
+  IdentifyOperation.PREPEND,
+  IdentifyOperation.POSTINSERT,
+  IdentifyOperation.POSTINSERT,
+];

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

@@ -0,0 +1,22 @@
+import { Event, IdentifyOperation } from '@amplitude/analytics-types';
+import { PROPERTY_ADD_OPERATIONS } from './constants';
+
+export const parseUserProperties = (event: Event) => {
+  if (!event.user_properties) {
+    return;
+  }
+  let userPropertiesObj = {};
+  const userPropertyKeys = Object.keys(event.user_properties);
+
+  userPropertyKeys.forEach((identifyKey) => {
+    if (PROPERTY_ADD_OPERATIONS.includes(identifyKey as IdentifyOperation)) {
+      const typedUserPropertiesOperation =
+        event.user_properties && (event.user_properties[identifyKey as IdentifyOperation] as Record<string, any>);
+      userPropertiesObj = {
+        ...userPropertiesObj,
+        ...typedUserPropertiesOperation,
+      };
+    }
+  });
+  return userPropertiesObj;
+};

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

@@ -1,5 +1,7 @@
-import { BrowserConfig, EnrichmentPlugin, Event } from '@amplitude/analytics-types';
+import { getAnalyticsConnector } from '@amplitude/analytics-client-common';
+import { BrowserConfig, EnrichmentPlugin, Event, SpecialEventType } from '@amplitude/analytics-types';
 import * as sessionReplay from '@amplitude/session-replay-browser';
+import { parseUserProperties } from './helpers';
 import { SessionReplayOptions } from './typings/session-replay';
 import { VERSION } from './version';
 
@@ -43,6 +45,9 @@ export class SessionReplayPlugin implements EnrichmentPlugin {
       }
     }
 
+    const identityStore = getAnalyticsConnector(this.config.instanceName).identityStore;
+    const userProperties = identityStore.getIdentity().userProperties;
+
     await sessionReplay.init(config.apiKey, {
       instanceName: this.config.instanceName,
       deviceId: this.config.deviceId,
@@ -63,6 +68,7 @@ export class SessionReplayPlugin implements EnrichmentPlugin {
       configEndpointUrl: this.options.configEndpointUrl,
       shouldInlineStylesheet: this.options.shouldInlineStylesheet,
       version: { type: 'plugin', version: VERSION },
+      userProperties: userProperties,
     }).promise;
   }
 
@@ -71,11 +77,20 @@ export class SessionReplayPlugin implements EnrichmentPlugin {
     // Choosing not to read from event object here, concerned about offline/delayed events messing up the state stored
     // in SR.
     if (this.config.sessionId && this.config.sessionId !== sessionReplay.getSessionId()) {
-      await sessionReplay.setSessionId(this.config.sessionId).promise;
+      const identityStore = getAnalyticsConnector(this.config.instanceName).identityStore;
+      const userProperties = identityStore.getIdentity().userProperties;
+      await sessionReplay.setSessionId(this.config.sessionId, this.config.deviceId, {
+        userProperties: userProperties || {},
+      }).promise;
     }
     // Treating config.sessionId as source of truth, if the event's session id doesn't match, the
     // event is not of the current session (offline/late events). In that case, don't tag the events
     if (this.config.sessionId && this.config.sessionId === event.session_id) {
+      let userProperties;
+      if (event.event_type === SpecialEventType.IDENTIFY) {
+        userProperties = parseUserProperties(event);
+      }
+      await sessionReplay.evaluateTargetingAndCapture({ event, userProperties });
       const sessionRecordingProperties = sessionReplay.getSessionReplayProperties();
       event.event_properties = {
         ...event.event_properties,

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

@@ -1,2 +1,2 @@
 // Autogenerated by `yarn version-file`. DO NOT EDIT
-export const VERSION = '1.6.20';
+export const VERSION = '1.7.0-srtargeting.0';

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

@@ -0,0 +1,40 @@
+import { SpecialEventType } from '@amplitude/analytics-types';
+import { parseUserProperties } from '../src/helpers';
+
+describe('helpers', () => {
+  test('should return undefined if no user properties', () => {
+    const userProperties = parseUserProperties({
+      event_type: SpecialEventType.IDENTIFY,
+      session_id: 123,
+    });
+    expect(userProperties).toEqual(undefined);
+  });
+
+  test('should parse properties from their operation', () => {
+    const userProperties = parseUserProperties({
+      event_type: SpecialEventType.IDENTIFY,
+      user_properties: {
+        $set: {
+          plan_id: 'free',
+        },
+      },
+      session_id: 123,
+    });
+    expect(userProperties).toEqual({
+      plan_id: 'free',
+    });
+  });
+
+  test('should return an empty object if operations are not additive', () => {
+    const userProperties = parseUserProperties({
+      event_type: SpecialEventType.IDENTIFY,
+      user_properties: {
+        $remove: {
+          plan_id: 'free',
+        },
+      },
+      session_id: 123,
+    });
+    expect(userProperties).toEqual({});
+  });
+});

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

@@ -1,7 +1,8 @@
-import { BrowserClient, BrowserConfig, LogLevel, Logger, Plugin } from '@amplitude/analytics-types';
+import { BrowserClient, BrowserConfig, LogLevel, Logger, Plugin, SpecialEventType } from '@amplitude/analytics-types';
 import * as sessionReplayBrowser from '@amplitude/session-replay-browser';
 import { SessionReplayPlugin, sessionReplayPlugin } from '../src/session-replay';
 import { VERSION } from '../src/version';
+import * as AnalyticsClientCommon from '@amplitude/analytics-client-common';
 
 jest.mock('@amplitude/session-replay-browser');
 type MockedSessionReplayBrowser = jest.Mocked<typeof import('@amplitude/session-replay-browser')>;
@@ -11,7 +12,7 @@ type MockedLogger = jest.Mocked<Logger>;
 type MockedBrowserClient = jest.Mocked<BrowserClient>;
 
 describe('SessionReplayPlugin', () => {
-  const { init, setSessionId, getSessionReplayProperties, shutdown, getSessionId } =
+  const { init, setSessionId, getSessionReplayProperties, evaluateTargetingAndCapture, shutdown, getSessionId } =
     sessionReplayBrowser as MockedSessionReplayBrowser;
   const mockLoggerProvider: MockedLogger = {
     error: jest.fn(),
@@ -93,6 +94,30 @@ describe('SessionReplayPlugin', () => {
       expect(sessionReplay.config.flushIntervalMillis).toBe(0);
     });
 
+    test('should pass user properties to plugin', async () => {
+      const updatedConfig: BrowserConfig = { ...mockConfig, sessionId: 456, instanceName: 'browser-sdk' };
+
+      const mockUserProperties = {
+        plan_id: 'free',
+      };
+      jest.spyOn(AnalyticsClientCommon, 'getAnalyticsConnector').mockReturnValue({
+        identityStore: {
+          getIdentity: () => {
+            return {
+              userProperties: mockUserProperties,
+            };
+          },
+        },
+      } as unknown as ReturnType<typeof AnalyticsClientCommon.getAnalyticsConnector>);
+      const sessionReplay = new SessionReplayPlugin();
+      await sessionReplay.setup(updatedConfig);
+      expect(init).toHaveBeenCalledTimes(1);
+      expect(init).toHaveBeenCalledWith(
+        mockConfig.apiKey,
+        expect.objectContaining({ userProperties: mockUserProperties }),
+      );
+    });
+
     describe('defaultTracking', () => {
       test('should not change defaultTracking if its set to true', async () => {
         const sessionReplay = new SessionReplayPlugin();
@@ -182,6 +207,7 @@ describe('SessionReplayPlugin', () => {
           type: 'plugin',
           version: VERSION,
         },
+        userProperties: {},
       });
     });
   });
@@ -210,6 +236,55 @@ describe('SessionReplayPlugin', () => {
       });
     });
 
+    test('should evaluate targeting, passing the event', async () => {
+      const sessionReplay = sessionReplayPlugin();
+      await sessionReplay.setup(mockConfig, mockAmplitude);
+      getSessionReplayProperties.mockReturnValueOnce({
+        '[Amplitude] Session Replay ID': '123',
+      });
+      const event = {
+        event_type: 'event_type',
+        event_properties: {
+          property_a: true,
+          property_b: 123,
+        },
+        session_id: 123,
+      };
+
+      await sessionReplay.execute(event);
+
+      expect(evaluateTargetingAndCapture).toHaveBeenCalledWith({
+        event: event,
+        userProperties: undefined,
+      });
+    });
+
+    test('should parse user properties for identify event', async () => {
+      const sessionReplay = sessionReplayPlugin();
+      await sessionReplay.setup(mockConfig, mockAmplitude);
+      getSessionReplayProperties.mockReturnValueOnce({
+        '[Amplitude] Session Replay ID': '123',
+      });
+      const event = {
+        event_type: SpecialEventType.IDENTIFY,
+        user_properties: {
+          $set: {
+            plan_id: 'free',
+          },
+        },
+        session_id: 123,
+      };
+
+      await sessionReplay.execute(event);
+
+      expect(evaluateTargetingAndCapture).toHaveBeenCalledWith({
+        event: event,
+        userProperties: {
+          plan_id: 'free',
+        },
+      });
+    });
+
     test('should not add event property for for event with mismatching session id.', async () => {
       const sessionReplay = sessionReplayPlugin();
       await sessionReplay.setup({ ...mockConfig });
@@ -242,7 +317,55 @@ describe('SessionReplayPlugin', () => {
       sessionReplay.config.sessionId = 456;
       await sessionReplay.execute(newEvent);
       expect(setSessionId).toHaveBeenCalledTimes(1);
-      expect(setSessionId).toHaveBeenCalledWith(456);
+      expect(setSessionId).toHaveBeenCalledWith(456, '1a2b3c', { userProperties: {} });
+    });
+
+    test('should update the session id on any event and pass along user properties', async () => {
+      const sessionReplay = new SessionReplayPlugin();
+      await sessionReplay.setup(mockConfig);
+
+      const event = {
+        event_type: 'session_start',
+        session_id: 456,
+      };
+      const mockUserProperties = {
+        plan_id: 'free',
+      };
+      jest.spyOn(AnalyticsClientCommon, 'getAnalyticsConnector').mockReturnValue({
+        identityStore: {
+          getIdentity: () => {
+            return {
+              userProperties: mockUserProperties,
+            };
+          },
+        },
+      } as unknown as ReturnType<typeof AnalyticsClientCommon.getAnalyticsConnector>);
+      sessionReplay.config.sessionId = 456;
+      await sessionReplay.execute(event);
+      expect(setSessionId).toHaveBeenCalledTimes(1);
+      expect(setSessionId).toHaveBeenCalledWith(456, '1a2b3c', { userProperties: mockUserProperties });
+    });
+    test('should update the session id on any event and pass along empty obj for user properties', async () => {
+      const sessionReplay = new SessionReplayPlugin();
+      await sessionReplay.setup(mockConfig);
+
+      const event = {
+        event_type: 'session_start',
+        session_id: 456,
+      };
+      jest.spyOn(AnalyticsClientCommon, 'getAnalyticsConnector').mockReturnValue({
+        identityStore: {
+          getIdentity: () => {
+            return {
+              userProperties: undefined,
+            };
+          },
+        },
+      } as unknown as ReturnType<typeof AnalyticsClientCommon.getAnalyticsConnector>);
+      sessionReplay.config.sessionId = 456;
+      await sessionReplay.execute(event);
+      expect(setSessionId).toHaveBeenCalledTimes(1);
+      expect(setSessionId).toHaveBeenCalledWith(456, '1a2b3c', { userProperties: {} });
     });
 
     test('should not update if session id unchanged', async () => {

packages/session-replay-browser/README.md

@@ -47,8 +47,18 @@ sessionReplay.init(API_KEY, {
 });
 ```
 
-### 3. Get session replay event properties
-Any event that occurs within the span of a session replay must be tagged with properties that signal to Amplitude to include it in the scope of the replay. The following shows an example of how to use the properties
+### 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.evaluateTargetingAndCapture({ event: {
+  event_type: EVENT_NAME,
+  time: EVENT_TIMESTAMP,
+  event_properties: eventProperties
+} });
+```
+
+### 4. Get session replay event properties
+Any event must be tagged with properties that signal to Amplitude to include it in the scope of the replay. The following shows an example of how to use the properties.
 ```typescript
 const sessionReplayProperties = sessionReplay.getSessionReplayProperties();
 track(EVENT_NAME, {
@@ -57,7 +67,7 @@ track(EVENT_NAME, {
 })
 ```
 
-### 4. Update session id
+### 5. Update session id
 Any time that the session id for the user changes, the session replay SDK must be notified of that change. Update the session id via the following method:
 ```typescript
 sessionReplay.setSessionId(UNIX_TIMESTAMP)
@@ -67,7 +77,7 @@ You can optionally pass a new device id as a second argument as well:
 sessionReplay.setSessionId(UNIX_TIMESTAMP, deviceId)
 ```
 
-### 5. Shutdown (optional)
+### 6. Shutdown (optional)
 If at any point you would like to discontinue collection of session replays, for example in a part of your application where you would not like sessions to be collected, you can use the following method to stop collection and remove collection event listeners.
 ```typescript
 sessionReplay.shutdown()