@spotify-confidence/session-recording 0.17.2 → 0.17.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.17.3](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.17.2...session-recording-v0.17.3) (2026-06-16)
+
+
+### ✨ New Features
+
+* add route parameterization for route change and meta events ([#370](https://github.com/spotify/confidence-sdk-js/issues/370)) ([6efbee0](https://github.com/spotify/confidence-sdk-js/commit/6efbee08776c88b05dfa0949844f6c330bb0bcaa))
+* emit flag evaluations into session recordings ([#369](https://github.com/spotify/confidence-sdk-js/issues/369)) ([3728c6d](https://github.com/spotify/confidence-sdk-js/commit/3728c6d682f97c3b2f18c8979dc91c50328b2345))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.17.3
+    * @spotify-confidence/csr-recorder bumped to 0.17.3
+
 ## [0.17.2](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.17.1...session-recording-v0.17.2) (2026-06-15)
 
 

package/README.md

@@ -92,6 +92,25 @@ const recorder = initSessionRecorder({
 });
 ```
 
+## Route parameterization
+
+Routes containing dynamic segments (such as IDs in the URL) are automatically normalized into patterns — for example, `/users/123/profile` becomes `/users/:id/profile`. This ensures that per-page metrics are grouped by route rather than by individual page visit, keeping dashboards meaningful and query performance fast.
+
+If your app uses URL patterns that aren't automatically detected, you can provide a custom `parameterizeRoute` function to control how routes are grouped:
+
+```typescript
+import { defaultParameterizeRoute } from '@spotify-confidence/csr-recorder';
+
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  parameterizeRoute: route => {
+    return defaultParameterizeRoute(route).replace(/\/teams\/[^/]+/, '/teams/:slug');
+  },
+});
+```
+
+See the [`@spotify-confidence/csr-recorder` README](../csr-recorder/README.md#route-parameterization) for the full list of default patterns.
+
 ## Manual mode
 
 Use `manual` mode to control when recording starts — useful for gating on user consent or feature flags.

package/dist/index.cjs

@@ -44,6 +44,33 @@ function validateMeasureValue(value) {
 const DEFAULT_MASK_SELECTORS = ["[data-csr-mask]"];
 const DEFAULT_BLOCK_SELECTORS = ["[data-csr-block]"];
 //#endregion
+//#region ../csr-recorder/src/route-parameterizer.ts
+const SEGMENT_PATTERNS = [
+	{
+		pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+		replacement: ":uuid"
+	},
+	{
+		pattern: /^\d+$/,
+		replacement: ":id"
+	},
+	{
+		pattern: /^[a-z][a-z0-9]{19}$/,
+		replacement: ":id"
+	},
+	{
+		pattern: /[0-9a-f]{20}/i,
+		replacement: ":id"
+	}
+];
+function defaultParameterizeRoute(route) {
+	return route.split("/").map((segment) => {
+		if (!segment) return segment;
+		for (const { pattern, replacement } of SEGMENT_PATTERNS) if (pattern.test(segment)) return replacement;
+		return segment;
+	}).join("/");
+}
+//#endregion
 //#region ../csr-recorder/src/recorder.ts
 var Recorder = class Recorder {
 	engine;
@@ -56,6 +83,7 @@ var Recorder = class Recorder {
 	originalPushState = null;
 	originalReplaceState = null;
 	popstateHandler = null;
+	parameterizeRoute;
 	constructor(options) {
 		this.engine = options.engine;
 		this.onEvent = options.onEvent;
@@ -66,7 +94,18 @@ var Recorder = class Recorder {
 	start(config) {
 		if (this.state === "recording") return;
 		this.state = "recording";
+		this.parameterizeRoute = config?.parameterizeRoute ?? defaultParameterizeRoute;
 		this.engine.start(config ?? {}, (event) => {
+			if (event.type === 4) {
+				const data = event.data;
+				if (typeof data?.href === "string") event = {
+					...event,
+					data: {
+						...data,
+						href: this.parameterizeHref(data.href)
+					}
+				};
+			}
 			this.onEvent(event);
 		});
 		if (typeof document !== "undefined") {
@@ -176,13 +215,25 @@ var Recorder = class Recorder {
 			return originalSend.call(this, body);
 		};
 	}
+	parameterizeHref(href) {
+		try {
+			const url = new URL(href);
+			url.pathname = this.parameterizeRoute(url.pathname);
+			return url.toString();
+		} catch (_e) {
+			return this.parameterizeRoute(href);
+		}
+	}
 	emitRouteChange(from, to, trigger) {
 		if (from === to) return;
+		const paramFrom = this.parameterizeRoute(from);
+		const paramTo = this.parameterizeRoute(to);
+		if (paramFrom === paramTo) return;
 		const data = {
 			plugin: "csr:routeChange",
 			payload: {
-				from,
-				to,
+				from: paramFrom,
+				to: paramTo,
 				trigger
 			}
 		};
@@ -11116,6 +11167,31 @@ function record(onEvent, config) {
 	return () => recorder.stop();
 }
 //#endregion
+//#region src/flag-observer.ts
+function observeFlags(onFlagWrite) {
+	if (typeof window === "undefined") return () => {};
+	const confidence = window.__confidence ??= {};
+	const existing = confidence.flags ?? {};
+	const target = { ...existing };
+	confidence.flags = new Proxy(target, { set(_target, prop, value) {
+		if (typeof prop === "string" && value && typeof value.variant === "string") {
+			_target[prop] = value;
+			onFlagWrite({
+				flagKey: prop,
+				variant: value.variant
+			});
+		}
+		return true;
+	} });
+	for (const [name, data] of Object.entries(existing)) if (data && typeof data.variant === "string") onFlagWrite({
+		flagKey: name,
+		variant: data.variant
+	});
+	return () => {
+		confidence.flags = { ...target };
+	};
+}
+//#endregion
 //#region ../csr-common/src/uploader/client-context.ts
 var import_es5 = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function(e, t) {
@@ -13077,7 +13153,7 @@ function writeCounter(counter) {
 }
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.17.2";
+const SDK_VERSION = "0.17.3";
 //#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://recording.confidence.dev";
@@ -13099,6 +13175,7 @@ function initSessionRecorder(options) {
 	const debugLogger = userLogger ? (msg) => userLogger(`[CSR] ${msg}`) : void 0;
 	let stopRecorder = null;
 	let closeUploader = null;
+	let stopObservingFlags = null;
 	let sendEvent = null;
 	let started = false;
 	let stopped = false;
@@ -13108,7 +13185,8 @@ function initSessionRecorder(options) {
 		maskInputs: options.maskInputs,
 		captureConsoleLogs: options.captureConsoleLogs,
 		captureNetworkRequests: options.captureNetworkRequests,
-		captureRouteChanges: options.captureRouteChanges
+		captureRouteChanges: options.captureRouteChanges,
+		parameterizeRoute: options.parameterizeRoute
 	};
 	async function initAndRecord(forceRecord) {
 		try {
@@ -13126,6 +13204,8 @@ function initSessionRecorder(options) {
 				debugLogger,
 				onTerminate: ({ reason }) => {
 					debugLogger?.(`Recording terminated: ${reason}`);
+					stopObservingFlags?.();
+					stopObservingFlags = null;
 					stopRecorder?.();
 					stopRecorder = null;
 					stopped = true;
@@ -13148,6 +13228,20 @@ function initSessionRecorder(options) {
 				}
 			};
 			stopRecorder = record(sendEvent, recordingConfig);
+			stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+				const data = {
+					plugin: "csr:flagEvaluation",
+					payload: {
+						flagKey,
+						variant
+					}
+				};
+				sendEvent?.({
+					type: 6,
+					timestamp: Date.now(),
+					data
+				});
+			});
 		} catch (err) {
 			debugLogger?.(`Recording disabled: ${err instanceof Error ? err.message : String(err)}`);
 		}
@@ -13165,6 +13259,8 @@ function initSessionRecorder(options) {
 		stop() {
 			if (stopped) return;
 			stopped = true;
+			stopObservingFlags?.();
+			stopObservingFlags = null;
 			stopRecorder?.();
 			stopRecorder = null;
 			sendEvent = null;

package/dist/index.d.cts

@@ -53,6 +53,16 @@ interface InitSessionRecorderOptions {
   captureNetworkRequests?: boolean;
   /** Capture client-side route changes (pathname only). Defaults to `true`. */
   captureRouteChanges?: boolean;
+  /**
+  * Transform a raw pathname into a route pattern before it is emitted in
+  * route-change and Meta events. For example, `/users/123/profile` becomes
+  * `/users/:id/profile`. This ensures per-page metrics are grouped by route
+  * rather than by individual page visit.
+  *
+  * Import `defaultParameterizeRoute` from `@spotify-confidence/csr-recorder`
+  * to compose with the built-in rules.
+  */
+  parameterizeRoute?: (route: string) => string;
   /** Backend base URL. Defaults to the Confidence production endpoint. */
   apiUrl?: string;
   /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */

package/dist/index.d.ts

@@ -53,6 +53,16 @@ interface InitSessionRecorderOptions {
   captureNetworkRequests?: boolean;
   /** Capture client-side route changes (pathname only). Defaults to `true`. */
   captureRouteChanges?: boolean;
+  /**
+  * Transform a raw pathname into a route pattern before it is emitted in
+  * route-change and Meta events. For example, `/users/123/profile` becomes
+  * `/users/:id/profile`. This ensures per-page metrics are grouped by route
+  * rather than by individual page visit.
+  *
+  * Import `defaultParameterizeRoute` from `@spotify-confidence/csr-recorder`
+  * to compose with the built-in rules.
+  */
+  parameterizeRoute?: (route: string) => string;
   /** Backend base URL. Defaults to the Confidence production endpoint. */
   apiUrl?: string;
   /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */

package/dist/index.js

@@ -43,6 +43,33 @@ function validateMeasureValue(value) {
 const DEFAULT_MASK_SELECTORS = ["[data-csr-mask]"];
 const DEFAULT_BLOCK_SELECTORS = ["[data-csr-block]"];
 //#endregion
+//#region ../csr-recorder/src/route-parameterizer.ts
+const SEGMENT_PATTERNS = [
+	{
+		pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+		replacement: ":uuid"
+	},
+	{
+		pattern: /^\d+$/,
+		replacement: ":id"
+	},
+	{
+		pattern: /^[a-z][a-z0-9]{19}$/,
+		replacement: ":id"
+	},
+	{
+		pattern: /[0-9a-f]{20}/i,
+		replacement: ":id"
+	}
+];
+function defaultParameterizeRoute(route) {
+	return route.split("/").map((segment) => {
+		if (!segment) return segment;
+		for (const { pattern, replacement } of SEGMENT_PATTERNS) if (pattern.test(segment)) return replacement;
+		return segment;
+	}).join("/");
+}
+//#endregion
 //#region ../csr-recorder/src/recorder.ts
 var Recorder = class Recorder {
 	engine;
@@ -55,6 +82,7 @@ var Recorder = class Recorder {
 	originalPushState = null;
 	originalReplaceState = null;
 	popstateHandler = null;
+	parameterizeRoute;
 	constructor(options) {
 		this.engine = options.engine;
 		this.onEvent = options.onEvent;
@@ -65,7 +93,18 @@ var Recorder = class Recorder {
 	start(config) {
 		if (this.state === "recording") return;
 		this.state = "recording";
+		this.parameterizeRoute = config?.parameterizeRoute ?? defaultParameterizeRoute;
 		this.engine.start(config ?? {}, (event) => {
+			if (event.type === 4) {
+				const data = event.data;
+				if (typeof data?.href === "string") event = {
+					...event,
+					data: {
+						...data,
+						href: this.parameterizeHref(data.href)
+					}
+				};
+			}
 			this.onEvent(event);
 		});
 		if (typeof document !== "undefined") {
@@ -175,13 +214,25 @@ var Recorder = class Recorder {
 			return originalSend.call(this, body);
 		};
 	}
+	parameterizeHref(href) {
+		try {
+			const url = new URL(href);
+			url.pathname = this.parameterizeRoute(url.pathname);
+			return url.toString();
+		} catch (_e) {
+			return this.parameterizeRoute(href);
+		}
+	}
 	emitRouteChange(from, to, trigger) {
 		if (from === to) return;
+		const paramFrom = this.parameterizeRoute(from);
+		const paramTo = this.parameterizeRoute(to);
+		if (paramFrom === paramTo) return;
 		const data = {
 			plugin: "csr:routeChange",
 			payload: {
-				from,
-				to,
+				from: paramFrom,
+				to: paramTo,
 				trigger
 			}
 		};
@@ -11097,6 +11148,31 @@ function record(onEvent, config) {
 	return () => recorder.stop();
 }
 //#endregion
+//#region src/flag-observer.ts
+function observeFlags(onFlagWrite) {
+	if (typeof window === "undefined") return () => {};
+	const confidence = window.__confidence ??= {};
+	const existing = confidence.flags ?? {};
+	const target = { ...existing };
+	confidence.flags = new Proxy(target, { set(_target, prop, value) {
+		if (typeof prop === "string" && value && typeof value.variant === "string") {
+			_target[prop] = value;
+			onFlagWrite({
+				flagKey: prop,
+				variant: value.variant
+			});
+		}
+		return true;
+	} });
+	for (const [name, data] of Object.entries(existing)) if (data && typeof data.variant === "string") onFlagWrite({
+		flagKey: name,
+		variant: data.variant
+	});
+	return () => {
+		confidence.flags = { ...target };
+	};
+}
+//#endregion
 //#region ../csr-common/src/uploader/client-context.ts
 var import_es5 = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function(e, t) {
@@ -13058,7 +13134,7 @@ function writeCounter(counter) {
 }
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.17.2";
+const SDK_VERSION = "0.17.3";
 //#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://recording.confidence.dev";
@@ -13080,6 +13156,7 @@ function initSessionRecorder(options) {
 	const debugLogger = userLogger ? (msg) => userLogger(`[CSR] ${msg}`) : void 0;
 	let stopRecorder = null;
 	let closeUploader = null;
+	let stopObservingFlags = null;
 	let sendEvent = null;
 	let started = false;
 	let stopped = false;
@@ -13089,7 +13166,8 @@ function initSessionRecorder(options) {
 		maskInputs: options.maskInputs,
 		captureConsoleLogs: options.captureConsoleLogs,
 		captureNetworkRequests: options.captureNetworkRequests,
-		captureRouteChanges: options.captureRouteChanges
+		captureRouteChanges: options.captureRouteChanges,
+		parameterizeRoute: options.parameterizeRoute
 	};
 	async function initAndRecord(forceRecord) {
 		try {
@@ -13107,6 +13185,8 @@ function initSessionRecorder(options) {
 				debugLogger,
 				onTerminate: ({ reason }) => {
 					debugLogger?.(`Recording terminated: ${reason}`);
+					stopObservingFlags?.();
+					stopObservingFlags = null;
 					stopRecorder?.();
 					stopRecorder = null;
 					stopped = true;
@@ -13129,6 +13209,20 @@ function initSessionRecorder(options) {
 				}
 			};
 			stopRecorder = record(sendEvent, recordingConfig);
+			stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+				const data = {
+					plugin: "csr:flagEvaluation",
+					payload: {
+						flagKey,
+						variant
+					}
+				};
+				sendEvent?.({
+					type: 6,
+					timestamp: Date.now(),
+					data
+				});
+			});
 		} catch (err) {
 			debugLogger?.(`Recording disabled: ${err instanceof Error ? err.message : String(err)}`);
 		}
@@ -13146,6 +13240,8 @@ function initSessionRecorder(options) {
 		stop() {
 			if (stopped) return;
 			stopped = true;
+			stopObservingFlags?.();
+			stopObservingFlags = null;
 			stopRecorder?.();
 			stopRecorder = null;
 			sendEvent = null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/session-recording",
   "license": "Apache-2.0",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/spotify/confidence-sdk-js.git",
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@spotify-confidence/csr-common": "^0.17.2",
-    "@spotify-confidence/csr-recorder": "^0.17.2"
+    "@spotify-confidence/csr-common": "^0.17.3",
+    "@spotify-confidence/csr-recorder": "^0.17.3"
   },
   "module": "./dist/index.js",
   "exports": {

package/src/flag-observer.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { observeFlags, type FlagWrite } from './flag-observer';
+
+describe('observeFlags', () => {
+  beforeEach(() => {
+    delete (window as any).__confidence;
+  });
+
+  it('calls back when a flag is written after observation starts', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment-a' };
+
+    expect(writes).toEqual([{ flagKey: 'my-flag', variant: 'treatment-a' }]);
+  });
+
+  it('emits snapshot entries for pre-existing flags', () => {
+    (window as any).__confidence = {
+      flags: {
+        'flag-a': { variant: 'v1' },
+        'flag-b': { variant: 'v2' },
+      },
+    };
+
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    expect(writes).toContainEqual({ flagKey: 'flag-a', variant: 'v1' });
+    expect(writes).toContainEqual({ flagKey: 'flag-b', variant: 'v2' });
+  });
+
+  it('observes new writes after reading the snapshot', () => {
+    (window as any).__confidence = {
+      flags: { existing: { variant: 'old' } },
+    };
+
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['new-flag'] = { variant: 'new' };
+
+    expect(writes).toHaveLength(2);
+    expect(writes[0]).toEqual({ flagKey: 'existing', variant: 'old' });
+    expect(writes[1]).toEqual({ flagKey: 'new-flag', variant: 'new' });
+  });
+
+  it('cleanup replaces proxy with plain copy', () => {
+    const writes: FlagWrite[] = [];
+    const cleanup = observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['flag-a'] = { variant: 'v1' };
+    expect(writes).toHaveLength(1);
+
+    cleanup();
+
+    (window as any).__confidence.flags['flag-b'] = { variant: 'v2' };
+    expect(writes).toHaveLength(1);
+  });
+
+  it('preserves data after cleanup', () => {
+    observeFlags(() => {});
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment' };
+
+    const cleanup = observeFlags(() => {});
+    cleanup();
+
+    expect((window as any).__confidence.flags['my-flag']).toEqual({ variant: 'treatment' });
+  });
+
+  it('ignores writes with missing variant', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags.bad = { noVariant: true };
+
+    expect(writes).toHaveLength(0);
+  });
+
+  it('ignores writes with non-string variant', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags.bad = { variant: 42 };
+
+    expect(writes).toHaveLength(0);
+  });
+
+  it('initializes window.__confidence if not present', () => {
+    observeFlags(() => {});
+
+    expect((window as any).__confidence).toBeDefined();
+    expect((window as any).__confidence.flags).toBeDefined();
+  });
+});

package/src/flag-observer.ts

@@ -0,0 +1,32 @@
+export type FlagWrite = { flagKey: string; variant: string };
+export type FlagWriteCallback = (write: FlagWrite) => void;
+
+export function observeFlags(onFlagWrite: FlagWriteCallback): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const confidence = ((window as any).__confidence ??= {});
+  const existing: Record<string, { variant: string }> = confidence.flags ?? {};
+  const target: Record<string, { variant: string }> = { ...existing };
+
+  const proxy = new Proxy(target, {
+    set(_target, prop, value) {
+      if (typeof prop === 'string' && value && typeof value.variant === 'string') {
+        _target[prop] = value;
+        onFlagWrite({ flagKey: prop, variant: value.variant });
+      }
+      return true;
+    },
+  });
+
+  confidence.flags = proxy;
+
+  for (const [name, data] of Object.entries(existing)) {
+    if (data && typeof (data as any).variant === 'string') {
+      onFlagWrite({ flagKey: name, variant: (data as any).variant });
+    }
+  }
+
+  return () => {
+    confidence.flags = { ...target };
+  };
+}

package/src/index.ts

@@ -4,10 +4,12 @@ import {
   RecordingEventType,
   type TagPluginData,
   type MeasurePluginData,
+  type FlagEvaluationPluginData,
   validateKey,
   validateTagValue,
   validateMeasureValue,
 } from '@spotify-confidence/csr-common';
+import { observeFlags } from './flag-observer';
 import { createUploader, type ClientContext } from '@spotify-confidence/csr-common/uploader';
 import { SDK_VERSION } from './version';
 
@@ -30,6 +32,16 @@ export interface InitSessionRecorderOptions {
   captureNetworkRequests?: boolean;
   /** Capture client-side route changes (pathname only). Defaults to `true`. */
   captureRouteChanges?: boolean;
+  /**
+   * Transform a raw pathname into a route pattern before it is emitted in
+   * route-change and Meta events. For example, `/users/123/profile` becomes
+   * `/users/:id/profile`. This ensures per-page metrics are grouped by route
+   * rather than by individual page visit.
+   *
+   * Import `defaultParameterizeRoute` from `@spotify-confidence/csr-recorder`
+   * to compose with the built-in rules.
+   */
+  parameterizeRoute?: (route: string) => string;
   /** Backend base URL. Defaults to the Confidence production endpoint. */
   apiUrl?: string;
   /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */
@@ -86,6 +98,7 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
 
   let stopRecorder: (() => void) | null = null;
   let closeUploader: (() => void) | null = null;
+  let stopObservingFlags: (() => void) | null = null;
   let sendEvent: ((event: unknown) => void) | null = null;
   let started = false;
   let stopped = false;
@@ -97,6 +110,7 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
     captureConsoleLogs: options.captureConsoleLogs,
     captureNetworkRequests: options.captureNetworkRequests,
     captureRouteChanges: options.captureRouteChanges,
+    parameterizeRoute: options.parameterizeRoute,
   };
 
   async function initAndRecord(forceRecord: boolean) {
@@ -115,6 +129,8 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
         debugLogger,
         onTerminate: ({ reason }) => {
           debugLogger?.(`Recording terminated: ${reason}`);
+          stopObservingFlags?.();
+          stopObservingFlags = null;
           stopRecorder?.();
           stopRecorder = null;
           stopped = true;
@@ -142,6 +158,18 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
       };
 
       stopRecorder = record(sendEvent, recordingConfig);
+
+      stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+        const data: FlagEvaluationPluginData = {
+          plugin: 'csr:flagEvaluation',
+          payload: { flagKey, variant },
+        };
+        sendEvent?.({
+          type: RecordingEventType.Plugin,
+          timestamp: Date.now(),
+          data,
+        });
+      });
     } catch (err) {
       debugLogger?.(`Recording disabled: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -163,6 +191,8 @@ export function initSessionRecorder(options: InitSessionRecorderOptions): Sessio
     stop() {
       if (stopped) return;
       stopped = true;
+      stopObservingFlags?.();
+      stopObservingFlags = null;
       stopRecorder?.();
       stopRecorder = null;
       sendEvent = null;

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '0.17.2';
+export const SDK_VERSION = '0.17.3';