\n\n---\n\n> For complete instructions for how to get started with the Splunk distribution of OpenTelemetry JavaScript for Web, see [Install the Browser RUM agent for Splunk RUM](https://quickdraw.splunk.com/redirect/?product=Observability&location=github.rum.get.started&version=current), [Instrument browser-based web applications for Splunk RUM](https://quickdraw.splunk.com/redirect/?product=Observability&location=github.browser.rum&version=current) and [Record browser sessions](https://help.splunk.com/en/splunk-observability-cloud/monitor-end-user-experience/real-user-monitoring/replay-user-sessions/record-browser-sessions).\n\n**Privacy-aware visual session replay for web applications.** The Splunk Session Recorder extends [`@splunk/otel-web`](../web/) with comprehensive session recording capabilities, correlating visual user interactions with OpenTelemetry telemetry for enhanced debugging and user experience analysis.\n\n## đ Installation & Setup\n\n### Package Manager Installation\n\n#### 1. Install the Packages\n\n```bash\n# Install both core RUM and session recorder\nnpm install @splunk/otel-web @splunk/otel-web-session-recorder\n# or\npnpm add @splunk/otel-web @splunk/otel-web-session-recorder\n# or\nyarn add @splunk/otel-web @splunk/otel-web-session-recorder\n```\n\n#### 2. Initialize RUM and Session Recorder\n\n```typescript\nimport { SplunkRum } from '@splunk/otel-web'\nimport SplunkSessionRecorder from '@splunk/otel-web-session-recorder'\n\n// Initialize core RUM first\nSplunkRum.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tapplicationName: 'my-web-app',\n\tdeploymentEnvironment: 'production',\n})\n\n// Then initialize session recorder\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n})\n```\n\n### CDN Installation\n\n#### 1. Load the Scripts\n\nChoose a versioning strategy based on your needs:\n\n**Major Version Lock (Recommended)**\n\n```html\n\n\n\n```\n\n**Minor Version Lock**\n\n```html\n\n\n\n```\n\n**Exact Version Lock**\n\n```html\n\n\"\n>\n\"\n>\n```\n\n**Latest Version (Not Recommended)**\n\n> â ī¸ **Warning:** The `latest` tag has been deprecated and now defaults to version `2.5.1`. To receive future updates while avoiding breaking changes, we recommend pinning your configuration to a specific major version (e.g., `v3` or `v2`).\n\n> đ For version numbers and integrity hashes, see [GitHub Releases](https://github.com/signalfx/splunk-otel-js-web/releases).\n>\n> đ For detailed CDN setup instructions, see the [official documentation](https://quickdraw.splunk.com/redirect/?product=Observability&location=github.rum.get.started&version=current).\n\n#### 2. Initialize RUM and Session Recorder\n\n```html\n\n```\n\n#### Complete CDN Example\n\n```html\n\n\n\t\n\t\tMy Web App with Session Recording\n\n\t\t\n\t\t\n\n\t\t\n\t\t\n\n\t\t\n\t\n\t\n\t\t\n\t\n\n```\n\n> â ī¸ **Important**: Always call `SplunkRum.init()` before `SplunkSessionRecorder.init()`.\n\n## âī¸ Configuration Options\n\n| Option | Type | Required | Default | Description |\n| ---------------------------- | ------------------------------------------ | -------- | -------- | ---------------------------------------------------------- |\n| `realm` | `string` | â | - | Splunk realm (us0, us1, eu0, etc.) |\n| `rumAccessToken` | `string` | â | - | RUM access token for authentication |\n| `beaconEndpoint` | `string` | â | - | Custom destination URL for captured data (overrides realm) |\n| `debug` | `boolean` | â | `false` | Enable debug logging |\n| `persistFailedReplayData` | `boolean \\| 'indexeddb' \\| 'localstorage'` | â | `true` | Persistence strategy for failed uploads (see below) |\n| `maskAllInputs` | `boolean` | â | `true` | Mask all form input values |\n| `maskAllText` | `boolean` | â | `false` | Mask all text content |\n| `sensitivityRules` | `SensitivityRule[]` | â | `[]` | Custom rules for masking, unmasking, or excluding elements |\n| `features.backgroundService` | `string \\| boolean` | â | `false` | Custom URL for background service worker |\n| `features.canvas` | `boolean` | â | `false` | Record canvas elements |\n| `features.iframes` | `boolean` | â | `false` | Record iframe content |\n| `features.video` | `boolean` | â | `false` | Record video elements |\n| `features.cacheAssets` | `boolean` | â | `true` | Cache assets for replay |\n| `features.packAssets` | `boolean \\| PackAssetsConfig` | â | `true` | Pack assets to reduce payload size |\n| `maxExportIntervalMs` | `number` | â | `5000` | Maximum interval between data exports (milliseconds) |\n| `logLevel` | `'debug' \\| 'info' \\| 'warn' \\| 'error'` | â | `'warn'` | Logging level for session recorder |\n\n### Replay Data Persistence\n\nControls how session replay data is persisted when upload requests fail:\n\n| Value | Description |\n| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `true` | Default. Uses the session replay script's built-in IndexedDB persistence and sends replay logs as OTLP/protobuf. Segments are stored in IndexedDB and retried on next page load. |\n| `'localstorage'` | Failed OTLP log exports are queued in localStorage (2 MB budget) and retried on next page load. |\n| `'indexeddb'` | Same as true. |\n| `false` | Disables persistence entirely. |\n\n```typescript\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tpersistFailedReplayData: 'indexeddb',\n})\n```\n\n### Sensitivity Rules Configuration\n\n```typescript\ninterface SensitivityRule {\n\trule: 'mask' | 'unmask' | 'exclude'\n\tselector: string // CSS selector\n}\n\n// Example usage\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tsensitivityRules: [\n\t\t{ rule: 'mask', selector: '.sensitive-data' },\n\t\t{ rule: 'exclude', selector: '.payment-form' },\n\t\t{ rule: 'unmask', selector: '.public-content' },\n\t],\n})\n```\n\n### Background Service Configuration\n\nThe background service is used to offload session replay processing to a 3rd party iframe (separate thread), improving performance by preventing the session replay logic from blocking the main thread.\n**It is required for image compression** - the background service handles compressing captured images to reduce payload size during session replay.\n\n**When to customize:**\n\n- Self-hosting the session recorder files\n- Using a custom Content Security Policy (CSP)\n- Deploying behind a firewall that blocks CDN access\n\n```typescript\n// Example: Self-hosted background service - ensure the domain is different from the main domain to ensure the background service is loaded in a separate thread.\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tfeatures: {\n\t\tbackgroundService: 'https://my-other-domain.com/assets/background-service.html',\n\t},\n})\n\n// Example: spunk domain\n// It will load an 3rd party iframe (background service) from this domain 'https://cdn.observability.splunkcloud.com/o11y-gdi-rum//background-service.html'\n// Ensure you have this domain whitelisted in your CSP config\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tfeatures: {\n\t\tbackgroundService: true,\n\t},\n})\n```\n\n> đĄ **Default behavior:** If not specified, asset processing is not offloaded and is handled on the main page thread.\n>\n> đ **File location:** When using npm installation, find `background-service.html` in `node_modules/@splunk/otel-web-session-recorder/dist/artifacts` to copy to your static assets or use `true` and load it from CDN.\n\n### Asset Packing Configuration\n\n```typescript\ninterface PackAssetsConfig {\n\tfonts?: boolean // Pack font assets\n\tstyles?: boolean // Pack CSS styles\n\timages?:\n\t\t| boolean\n\t\t| {\n\t\t\t\tonlyViewportImages?: boolean // Only pack visible images\n\t\t\t\tpack?: boolean // Enable image packing\n\t\t\t\tquality?: number // JPEG quality (0-1). Only available when backgroundService is set, otherwise silently ignored\n\t\t }\n}\n\n// Example usage\nSplunkSessionRecorder.init({\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\tfeatures: {\n\t\tpackAssets: {\n\t\t\tfonts: true,\n\t\t\tstyles: true,\n\t\t\timages: {\n\t\t\t\tonlyViewportImages: true,\n\t\t\t\tpack: true,\n\t\t\t\tquality: 0.8,\n\t\t\t},\n\t\t},\n\t},\n})\n```\n\n### Complete Configuration Example\n\n```typescript\nimport SplunkSessionRecorder from '@splunk/otel-web-session-recorder'\n\nSplunkSessionRecorder.init({\n\t// Required settings\n\trealm: 'us1',\n\trumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',\n\n\t// Optional: Custom endpoint (overrides realm)\n\tbeaconEndpoint: 'https://custom-endpoint.com/v1/rumreplay',\n\n\t// Privacy & Security\n\tmaskAllInputs: true,\n\tmaskAllText: false,\n\tsensitivityRules: [\n\t\t{ rule: 'exclude', selector: '.payment-form' },\n\t\t{ rule: 'mask', selector: '.sensitive-data' },\n\t\t{ rule: 'unmask', selector: '.public-info' },\n\t],\n\n\t// Feature Control\n\tfeatures: {\n\t\tbackgroundService: true,,\n\t\tcanvas: false, // Skip canvas recording for privacy\n\t\tiframes: false, // Skip iframe content\n\t\tvideo: false, // Skip video elements\n\t\tcacheAssets: true, // Cache assets for better replay\n\t\tpackAssets: {\n\t\t\t// Optimize asset packing\n\t\t\tfonts: true,\n\t\t\tstyles: true,\n\t\t\timages: {\n\t\t\t\tonlyViewportImages: true,\n\t\t\t\tpack: true,\n\t\t\t\tquality: 0.7,\n\t\t\t},\n\t\t},\n\t},\n\n\t// Performance\n\tmaxExportIntervalMs: 5000, // Export data every 5 seconds\n\tlogLevel: 'warn', // Log warnings and errors only\n\n\t// Advanced\n\tdebug: false, // Disable debug logging\n\tpersistFailedReplayData: true, // Store failed uploads for retry\n})\n```\n\n## đ ī¸ Troubleshooting\n\nFor troubleshooting issues with the Splunk Session Recorder, see [Troubleshoot browser instrumentation for Splunk Observability Cloud](https://quickdraw.splunk.com/redirect/?product=Observability&version=current&location=web.rum.troubleshooting) in the official documentation.\n\n## đ API Reference\n\n### SplunkSessionRecorder Class\n\n#### Static Methods\n\n| Method | Parameters | Returns | Description |\n| -------------- | ----------------------- | ------- | ------------------------------- |\n| `init(config)` | `SessionRecorderConfig` | `void` | Initialize session recorder |\n| `start()` | - | `void` | Start recording current session |\n| `stop()` | - | `void` | Stop recording current session |\n\n```typescript\ninterface SessionRecorderConfig {\n\t// Required\n\trealm: string\n\trumAccessToken: string\n\n\t// Privacy\n\tmaskAllInputs?: boolean\n\tmaskAllText?: boolean\n\tsensitivityRules?: SensitivityRule[]\n\n\t// Feature Control\n\tfeatures?: {\n\t\tbackgroundService?: string | boolean\n\t\tcanvas?: boolean\n\t\tiframes?: boolean\n\t\tvideo?: boolean\n\t\tcacheAssets?: boolean\n\t\tpackAssets?: boolean | PackAssetsConfig\n\t}\n\n\t// Performance\n\tmaxExportIntervalMs?: number\n\tlogLevel?: 'debug' | 'info' | 'warn' | 'error'\n\n\t// Advanced\n\tdebug?: boolean\n\tbeaconEndpoint?: string\n\tpersistFailedReplayData?: boolean | 'localstorage' | 'indexeddb'\n}\n\ninterface SensitivityRule {\n\trule: 'mask' | 'unmask' | 'exclude'\n\tselector: string\n}\n\ninterface UserInfo {\n\tid?: string\n\temail?: string\n\tattributes?: Record\n}\n```\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](../../LICENSE) for the full license text.\n\n---\n\n> âšī¸ SignalFx was acquired by Splunk in October 2019. See [Splunk SignalFx](https://www.splunk.com/en_us/investor-relations/acquisitions/signalfx.html) for more information.\n","readmeFilename":"README.md"}
![\"Latest](\"https://img.shields.io/github/v/release/signalfx/splunk-otel-js-web?include_prereleases&style=for-the-badge\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/v/@splunk/otel-web-session-recorder?style=for-the-badge\")
\n \n \n ![\"Apache](\"https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=for-the-badge\"){kind=icon}
\n \n \n ![\"Bundle](\"https://img.shields.io/bundlephobia/minzip/@splunk/otel-web-session-recorder?style=for-the-badge\")
\n \n