@spotify-confidence/csr-recorder 0.17.2 → 0.17.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.17.3](https://github.com/spotify/confidence-sdk-js/compare/csr-recorder-v0.17.2...csr-recorder-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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.17.3
+
 ## [0.17.2](https://github.com/spotify/confidence-sdk-js/compare/csr-recorder-v0.17.1...csr-recorder-v0.17.2) (2026-06-15)
 
 

package/README.md

@@ -27,6 +27,34 @@ const stop = record(
 stop();
 ```
 
+## 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.
+
+Default replacements:
+
+| Pattern                | Example                                | Replacement |
+| ---------------------- | -------------------------------------- | ----------- |
+| UUID                   | `550e8400-e29b-41d4-a716-446655440000` | `:uuid`     |
+| Numeric ID             | `123`                                  | `:id`       |
+| AIP-122 ID             | `cmvkznnjmbkc9rw2oxws`                 | `:id`       |
+| Hex string (20+ chars) | `507f1f77bcf86cd799439011`             | `:id`       |
+
+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 { record, defaultParameterizeRoute } from '@spotify-confidence/csr-recorder';
+
+const stop = record(event => {}, {
+  parameterizeRoute: route => {
+    // Apply defaults first, then handle your own patterns
+    return defaultParameterizeRoute(route).replace(/\/teams\/[^/]+/, '/teams/:slug');
+  },
+});
+```
+
+The same parameterization is also applied to the `href` in rrweb Meta events.
+
 ## rrweb version
 
 This package pins `rrweb@^2.0.0-alpha.20`. The rrweb 2.x line is in alpha but is the version we've validated against. The recording engine is bundled — consumers do not need rrweb as a peer dependency.

package/dist/index.cjs

@@ -10,6 +10,33 @@ let RecorderState = /* @__PURE__ */ function(RecorderState) {
 	return RecorderState;
 }({});
 //#endregion
+//#region 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 src/recorder.ts
 var Recorder = class Recorder {
 	engine;
@@ -22,6 +49,7 @@ var Recorder = class Recorder {
 	originalPushState = null;
 	originalReplaceState = null;
 	popstateHandler = null;
+	parameterizeRoute;
 	constructor(options) {
 		this.engine = options.engine;
 		this.onEvent = options.onEvent;
@@ -32,7 +60,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 === _spotify_confidence_csr_common.RecordingEventType.Meta) {
+				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") {
@@ -142,13 +181,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
 			}
 		};
@@ -11087,4 +11138,5 @@ exports.DEFAULT_MASK_SELECTORS = DEFAULT_MASK_SELECTORS;
 exports.Recorder = Recorder;
 exports.RecorderState = RecorderState;
 exports.RrwebEngine = RrwebEngine;
+exports.defaultParameterizeRoute = defaultParameterizeRoute;
 exports.record = record;

package/dist/index.d.cts

@@ -68,6 +68,22 @@ interface RecordingConfig {
   * hashes are stripped.
   */
   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.
+  *
+  * The default implementation replaces common dynamic segments:
+  * - UUIDs → `:uuid`
+  * - Numeric IDs → `:id`
+  * - AIP-122 IDs → `:id`
+  * - Long hex strings (20+ chars, e.g. MongoDB ObjectIDs) → `:id`
+  *
+  * Provide a custom function to handle application-specific patterns.
+  * Import `defaultParameterizeRoute` to compose with the built-in rules.
+  */
+  parameterizeRoute?: (route: string) => string;
 }
 declare enum RecorderState {
   Idle = "idle",
@@ -87,6 +103,7 @@ declare class Recorder {
   private originalPushState;
   private originalReplaceState;
   private popstateHandler;
+  private parameterizeRoute;
   constructor(options: RecorderOptions);
   get currentState(): RecorderState;
   start(config?: RecordingConfig): void;
@@ -94,6 +111,7 @@ declare class Recorder {
   private patchNetwork;
   private patchFetch;
   private patchXhr;
+  private parameterizeHref;
   private emitRouteChange;
   private static currentPathname;
   private patchRouting;
@@ -121,4 +139,7 @@ declare class RrwebEngine implements RecordingEngine {
 */
 declare function record(onEvent: (event: RecordingEvent) => void, config?: RecordingConfig): () => void;
 //#endregion
-export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, type RecorderOptions, RecorderState, type RecordingConfig, type RecordingEngine, RrwebEngine, record };
+//#region src/route-parameterizer.d.ts
+declare function defaultParameterizeRoute(route: string): string;
+//#endregion
+export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, type RecorderOptions, RecorderState, type RecordingConfig, type RecordingEngine, RrwebEngine, defaultParameterizeRoute, record };

package/dist/index.d.ts

@@ -68,6 +68,22 @@ interface RecordingConfig {
   * hashes are stripped.
   */
   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.
+  *
+  * The default implementation replaces common dynamic segments:
+  * - UUIDs → `:uuid`
+  * - Numeric IDs → `:id`
+  * - AIP-122 IDs → `:id`
+  * - Long hex strings (20+ chars, e.g. MongoDB ObjectIDs) → `:id`
+  *
+  * Provide a custom function to handle application-specific patterns.
+  * Import `defaultParameterizeRoute` to compose with the built-in rules.
+  */
+  parameterizeRoute?: (route: string) => string;
 }
 declare enum RecorderState {
   Idle = "idle",
@@ -87,6 +103,7 @@ declare class Recorder {
   private originalPushState;
   private originalReplaceState;
   private popstateHandler;
+  private parameterizeRoute;
   constructor(options: RecorderOptions);
   get currentState(): RecorderState;
   start(config?: RecordingConfig): void;
@@ -94,6 +111,7 @@ declare class Recorder {
   private patchNetwork;
   private patchFetch;
   private patchXhr;
+  private parameterizeHref;
   private emitRouteChange;
   private static currentPathname;
   private patchRouting;
@@ -121,4 +139,7 @@ declare class RrwebEngine implements RecordingEngine {
 */
 declare function record(onEvent: (event: RecordingEvent) => void, config?: RecordingConfig): () => void;
 //#endregion
-export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, type RecorderOptions, RecorderState, type RecordingConfig, type RecordingEngine, RrwebEngine, record };
+//#region src/route-parameterizer.d.ts
+declare function defaultParameterizeRoute(route: string): string;
+//#endregion
+export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, type RecorderOptions, RecorderState, type RecordingConfig, type RecordingEngine, RrwebEngine, defaultParameterizeRoute, record };

package/dist/index.js

@@ -9,6 +9,33 @@ let RecorderState = /* @__PURE__ */ function(RecorderState) {
 	return RecorderState;
 }({});
 //#endregion
+//#region 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 src/recorder.ts
 var Recorder = class Recorder {
 	engine;
@@ -21,6 +48,7 @@ var Recorder = class Recorder {
 	originalPushState = null;
 	originalReplaceState = null;
 	popstateHandler = null;
+	parameterizeRoute;
 	constructor(options) {
 		this.engine = options.engine;
 		this.onEvent = options.onEvent;
@@ -31,7 +59,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 === RecordingEventType.Meta) {
+				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") {
@@ -141,13 +180,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
 			}
 		};
@@ -11081,4 +11132,4 @@ function record(onEvent, config) {
 	return () => recorder.stop();
 }
 //#endregion
-export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, RecorderState, RrwebEngine, record };
+export { DEFAULT_BLOCK_SELECTORS, DEFAULT_MASK_SELECTORS, Recorder, RecorderState, RrwebEngine, defaultParameterizeRoute, record };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/csr-recorder",
   "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,7 +35,7 @@
   },
   "dependencies": {
     "@rrweb/rrweb-plugin-console-record": "^2.0.0-alpha.20",
-    "@spotify-confidence/csr-common": "^0.17.2",
+    "@spotify-confidence/csr-common": "^0.17.3",
     "rrweb": "^2.0.0-alpha.20"
   },
   "module": "./dist/index.js",

package/src/index.ts

@@ -9,3 +9,4 @@ export {
   DEFAULT_BLOCK_SELECTORS,
 } from './types';
 export { record } from './start-recording';
+export { defaultParameterizeRoute } from './route-parameterizer';

package/src/recorder-routing.test.ts

@@ -8,10 +8,15 @@ class MockEngine implements RecordingEngine {
   private onEvent: ((event: RecordingEvent) => void) | null = null;
   startCalled = false;
   stopCalled = false;
+  /** Events emitted synchronously during start(), simulating rrweb behaviour. */
+  eventsOnStart: RecordingEvent[] = [];
 
   start(_config: unknown, onEvent: (event: RecordingEvent) => void): void {
     this.startCalled = true;
     this.onEvent = onEvent;
+    for (const event of this.eventsOnStart) {
+      onEvent(event);
+    }
   }
 
   stop(): void {
@@ -117,6 +122,22 @@ describe('Recorder route change capture', () => {
     recorder.stop();
   });
 
+  it('does not emit when parameterized routes are identical', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.pushState({}, '', '/users/123');
+    history.pushState({}, '', '/users/456');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/users/:id');
+
+    recorder.stop();
+  });
+
   it('emits for popstate events', () => {
     const engine = new MockEngine();
     const onEvent = vi.fn();
@@ -140,6 +161,101 @@ describe('Recorder route change capture', () => {
     recorder.stop();
   });
 
+  it('parameterizes routes by default', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.pushState({}, '', '/users/123');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/users/:id');
+
+    recorder.stop();
+  });
+
+  it('parameterizes UUIDs by default', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.pushState({}, '', '/items/550e8400-e29b-41d4-a716-446655440000');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/items/:uuid');
+
+    recorder.stop();
+  });
+
+  it('uses a custom parameterizeRoute when provided', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({
+      parameterizeRoute: route => route.replace(/\/users\/[^/]+/, '/users/:userId'),
+    });
+
+    history.pushState({}, '', '/users/alice');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/users/:userId');
+
+    recorder.stop();
+  });
+
+  it('parameterizes href in meta events emitted by the engine', () => {
+    const engine = new MockEngine();
+    engine.eventsOnStart = [
+      {
+        type: RecordingEventType.Meta,
+        timestamp: 1,
+        data: { href: 'https://example.com/users/123/settings', width: 1920, height: 1080 },
+      },
+    ];
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    const metaEvents = (onEvent.mock.calls as [RecordingEvent][])
+      .map(([e]) => e)
+      .filter(e => e.type === RecordingEventType.Meta);
+
+    expect(metaEvents).toHaveLength(1);
+    expect((metaEvents[0].data as { href: string }).href).toBe('https://example.com/users/:id/settings');
+
+    recorder.stop();
+  });
+
+  it('parameterizes meta href using custom parameterizeRoute', () => {
+    const engine = new MockEngine();
+    engine.eventsOnStart = [
+      {
+        type: RecordingEventType.Meta,
+        timestamp: 1,
+        data: { href: 'https://example.com/teams/acme-corp/dashboard', width: 1920, height: 1080 },
+      },
+    ];
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({
+      parameterizeRoute: route => route.replace(/\/teams\/[^/]+/, '/teams/:slug'),
+    });
+
+    const metaEvents = (onEvent.mock.calls as [RecordingEvent][])
+      .map(([e]) => e)
+      .filter(e => e.type === RecordingEventType.Meta);
+
+    expect(metaEvents).toHaveLength(1);
+    expect((metaEvents[0].data as { href: string }).href).toBe('https://example.com/teams/:slug/dashboard');
+
+    recorder.stop();
+  });
+
   it('removes popstate listener on stop', () => {
     const addSpy = vi.spyOn(window, 'addEventListener');
     const removeSpy = vi.spyOn(window, 'removeEventListener');

package/src/recorder.ts

@@ -8,6 +8,7 @@ import {
 } from '@spotify-confidence/csr-common';
 import { RecorderOptions, RecorderState, RecordingConfig } from './types';
 import { RecordingEngine } from './engine';
+import { defaultParameterizeRoute } from './route-parameterizer';
 
 export class Recorder {
   private readonly engine: RecordingEngine;
@@ -20,6 +21,7 @@ export class Recorder {
   private originalPushState: typeof history.pushState | null = null;
   private originalReplaceState: typeof history.replaceState | null = null;
   private popstateHandler: (() => void) | null = null;
+  private parameterizeRoute!: (route: string) => string;
 
   constructor(options: RecorderOptions) {
     this.engine = options.engine;
@@ -35,7 +37,15 @@ export class Recorder {
       return;
     }
     this.state = RecorderState.Recording;
+    this.parameterizeRoute = config?.parameterizeRoute ?? defaultParameterizeRoute;
+
     this.engine.start(config ?? {}, event => {
+      if (event.type === RecordingEventType.Meta) {
+        const data = event.data as { href?: string };
+        if (typeof data?.href === 'string') {
+          event = { ...event, data: { ...data, href: this.parameterizeHref(data.href) } };
+        }
+      }
       this.onEvent(event);
     });
 
@@ -174,11 +184,24 @@ export class Recorder {
     };
   }
 
+  private parameterizeHref(href: string): string {
+    try {
+      const url = new URL(href);
+      url.pathname = this.parameterizeRoute(url.pathname);
+      return url.toString();
+    } catch (_e) {
+      return this.parameterizeRoute(href);
+    }
+  }
+
   private emitRouteChange(from: string, to: string, trigger: RouteChangeTrigger): void {
     if (from === to) return;
+    const paramFrom = this.parameterizeRoute(from);
+    const paramTo = this.parameterizeRoute(to);
+    if (paramFrom === paramTo) return;
     const data: RouteChangePluginData = {
       plugin: 'csr:routeChange',
-      payload: { from, to, trigger },
+      payload: { from: paramFrom, to: paramTo, trigger },
     };
     this.onEvent({
       type: RecordingEventType.Plugin,

package/src/route-parameterizer.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { defaultParameterizeRoute } from './route-parameterizer';
+
+describe('defaultParameterizeRoute', () => {
+  it('leaves static routes unchanged', () => {
+    expect(defaultParameterizeRoute('/users/settings')).toBe('/users/settings');
+  });
+
+  it('replaces numeric IDs', () => {
+    expect(defaultParameterizeRoute('/users/123')).toBe('/users/:id');
+    expect(defaultParameterizeRoute('/users/123/posts/456')).toBe('/users/:id/posts/:id');
+  });
+
+  it('replaces UUIDs', () => {
+    expect(defaultParameterizeRoute('/users/550e8400-e29b-41d4-a716-446655440000')).toBe('/users/:uuid');
+  });
+
+  it('replaces uppercase UUIDs', () => {
+    expect(defaultParameterizeRoute('/users/550E8400-E29B-41D4-A716-446655440000')).toBe('/users/:uuid');
+  });
+
+  it('replaces long hex strings (MongoDB ObjectIDs)', () => {
+    expect(defaultParameterizeRoute('/items/507f1f77bcf86cd799439011')).toBe('/items/:id');
+  });
+
+  it('handles mixed segments', () => {
+    expect(defaultParameterizeRoute('/org/550e8400-e29b-41d4-a716-446655440000/users/42/profile')).toBe(
+      '/org/:uuid/users/:id/profile',
+    );
+  });
+
+  it('preserves root path', () => {
+    expect(defaultParameterizeRoute('/')).toBe('/');
+  });
+
+  it('preserves empty string', () => {
+    expect(defaultParameterizeRoute('')).toBe('');
+  });
+
+  it('does not replace short hex strings', () => {
+    expect(defaultParameterizeRoute('/features/abcdef')).toBe('/features/abcdef');
+  });
+
+  it('does not replace words that look vaguely hex-ish', () => {
+    expect(defaultParameterizeRoute('/dashboard/feed')).toBe('/dashboard/feed');
+  });
+
+  it('handles trailing slash', () => {
+    expect(defaultParameterizeRoute('/users/123/')).toBe('/users/:id/');
+  });
+
+  it('replaces AIP-122 generated IDs', () => {
+    expect(defaultParameterizeRoute('/workflows/abtest/instances/cmvkznnjmbkc9rw2oxws/report')).toBe(
+      '/workflows/abtest/instances/:id/report',
+    );
+  });
+
+  it('replaces multiple AIP-122 IDs', () => {
+    expect(defaultParameterizeRoute('/admin/workflows/a0smva5nxuhv4yts6pax/instances/cmvkznnjmbkc9rw2oxws')).toBe(
+      '/admin/workflows/:id/instances/:id',
+    );
+  });
+
+  it('does not replace short lowercase strings as AIP-122', () => {
+    expect(defaultParameterizeRoute('/workflows/abtest')).toBe('/workflows/abtest');
+  });
+
+  it('replaces segments containing embedded hex IDs', () => {
+    expect(defaultParameterizeRoute('/items/prefix507f1f77bcf86cd799439011suffix')).toBe('/items/:id');
+  });
+
+  it('replaces MD5 hashes', () => {
+    expect(defaultParameterizeRoute('/cache/d41d8cd98f00b204e9800998ecf8427e')).toBe('/cache/:id');
+  });
+});

package/src/route-parameterizer.ts

@@ -0,0 +1,20 @@
+const SEGMENT_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
+  { 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' },
+  // AIP-122 generated IDs: 20-char lowercase alphanumeric starting with a letter
+  { pattern: /^[a-z][a-z0-9]{19}$/, replacement: ':id' },
+  { pattern: /[0-9a-f]{20}/i, replacement: ':id' },
+];
+
+export function defaultParameterizeRoute(route: string): string {
+  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('/');
+}

package/src/types.ts

@@ -55,6 +55,22 @@ export interface RecordingConfig {
    * hashes are stripped.
    */
   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.
+   *
+   * The default implementation replaces common dynamic segments:
+   * - UUIDs → `:uuid`
+   * - Numeric IDs → `:id`
+   * - AIP-122 IDs → `:id`
+   * - Long hex strings (20+ chars, e.g. MongoDB ObjectIDs) → `:id`
+   *
+   * Provide a custom function to handle application-specific patterns.
+   * Import `defaultParameterizeRoute` to compose with the built-in rules.
+   */
+  parameterizeRoute?: (route: string) => string;
 }
 
 export enum RecorderState {