Recordings SDK (Web)

The Recordings SDK captures user sessions in web browsers and streams them to Confidence. It’s a separate package from the flags SDKs: @spotify-confidence/session-recording. Recordings supports web browsers only. For the end-to-end setup, including roles and recording policies, see record user sessions.

Install

npm install @spotify-confidence/session-recording

Initialize the Recorder

import { initSessionRecorder } from '@spotify-confidence/session-recording';

const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  appVersion: '2.3.1',
  context: {
    plan: 'premium',
    checkout_version: 'one-page',
  },
});

clientSecret is a browser client secret for the environment you want to record.
appVersion stores an application version or commit hash on the recording.
context holds custom dimensions. Confidence uses context to evaluate recording rules before capture starts, and you can filter recordings by it. Don’t add direct personal identifiers, access tokens, or secrets to context.

initSessionRecorder always returns a recorder and doesn’t throw setup errors to the application. The SDK masks input values by default. Review privacy and data masking before you enable recording in a production environment.

Configuration Options

const recorder = initSessionRecorder({
  // Required
  clientSecret: '<your-client-secret>',

  // Context
  context: { visitor_id: 'user-42', buildVersion: '2.3.1' },

  // Privacy
  maskSelectors: ['.pii'],
  blockSelectors: ['video'],
  maskInputs: true, // default: true

  // Capture options
  captureConsoleLogs: true, // default: false
  captureNetworkRequests: false, // default: false
  captureRouteChanges: true, // default: true

  // Recording mode
  mode: 'automatic', // 'automatic' (default) or 'manual'

  // Self-hosted worker, only needed when CSP blocks data: and blob:
  // workerUrl: '/confidence-worker.js',

  // Debug
  debugLogger: message => console.debug(message),
});

Console and network capture can record sensitive data. See optional diagnostic data for the sanitize options before you enable them.

Capture Modes

In automatic mode, the default, the SDK starts capture when the session matches an active recording rule. Use manual mode to control when recording starts, for example after the user gives consent. start() applies the same rule, allocation, and sampling checks as automatic mode, so Confidence can still skip the session.

const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  mode: 'manual',
});

// Later, when ready:
recorder.start();

Recorder API

Member	Description
`start()`	Start recording. Does nothing in automatic mode.
`stop()`	Stop recording permanently. Safe to call more than once.
`tag(key, value?)`	Attach a string tag. Tags with the same key accumulate values.
`measure(key, value?)`	Record a numeric measurement. The SDK sums values with the same key.
`isRecording`	`true` while the recorder captures events.

See custom data for how to use tags and measurements.

Debug Logs

Pass a logger while you set up the SDK:

const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  debugLogger: message => console.debug(message),
});

The logger reports when recording starts, when Confidence skips the session, connection changes, and worker errors. Messages start with [CSR]. To turn on logging without changing code, run this in the browser console and reload the page:

sessionStorage.setItem('CSR_DEBUG', 'true');

Remove it with sessionStorage.removeItem('CSR_DEBUG').

Content Security Policy

The SDK uploads data from a Web Worker. If your site uses a Content Security Policy, allow these directives:

Directive	Value
`worker-src`	`data:` (default), `blob:` (automatic fallback), or `'self'` with a self-hosted worker
`connect-src`	`https://recording.confidence.dev wss://recording-ws.confidence.dev`

If your policy blocks both data: and blob:, copy the worker file to your static assets and pass its URL:

cp node_modules/@spotify-confidence/session-recording/dist/confidence-worker.js public/

const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  workerUrl: '/confidence-worker.js',
});

Copy the worker again after each SDK upgrade. If the versions differ, the SDK logs a WORKER MISMATCH warning through debugLogger.

Use with the Flags SDK

If you also use a Confidence flags SDK, keep the recording context and the flag evaluation context aligned. See feature flag integration.

Record User Sessions

Set up Recordings end to end

Privacy and Data Masking

Mask or block sensitive content

Route Parameterization

Group dynamic application routes

SDK Source

Review the package README on GitHub

Get Started

Feature Flags

Server SDKs

Client SDKs

Edge Resolvers

Events

Recordings

CLI

Install

Initialize the Recorder

Configuration Options

Capture Modes

Recorder API

Debug Logs

Content Security Policy

Use with the Flags SDK

Record User Sessions

Privacy and Data Masking

Route Parameterization

SDK Source

​Install

​Initialize the Recorder

​Configuration Options

​Capture Modes

​Recorder API

​Debug Logs

​Content Security Policy

​Use with the Flags SDK

​Related Resources

Record User Sessions

Privacy and Data Masking

Route Parameterization

SDK Source

Install

Initialize the Recorder

Configuration Options

Capture Modes

Recorder API

Debug Logs

Content Security Policy

Use with the Flags SDK

Related Resources