> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recordings SDK (Web)

> Install and configure the Confidence session recording SDK for web browsers.

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](/docs/guides/set-up-session-recordings).

## Install

```bash theme={null}
npm install @spotify-confidence/session-recording
```

## Initialize the Recorder

```typescript theme={null}
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](/docs/capabilities/recordings/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](/docs/capabilities/recordings/privacy)
before you enable recording in a production environment.

## Configuration Options

```typescript theme={null}
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](/docs/capabilities/recordings/privacy#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.

```typescript theme={null}
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](/docs/capabilities/recordings/custom-data) for how to use tags and measurements.

## Debug Logs

Pass a logger while you set up the SDK:

```typescript theme={null}
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:

```javascript theme={null}
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:

```bash theme={null}
cp node_modules/@spotify-confidence/session-recording/dist/confidence-worker.js public/
```

```typescript theme={null}
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](/docs/capabilities/recordings/feature-flag-integration).

## Related Resources

<CardGroup cols={2}>
  <Card title="Record User Sessions" href="/docs/guides/set-up-session-recordings">
    Set up Recordings end to end
  </Card>

  <Card title="Privacy and Data Masking" href="/docs/capabilities/recordings/privacy">
    Mask or block sensitive content
  </Card>

  <Card title="Route Parameterization" href="/docs/capabilities/recordings/route-parameterization">
    Group dynamic application routes
  </Card>

  <Card title="SDK Source" href="https://github.com/spotify/confidence-sdk-js/tree/main/csr/session-recording">
    Review the package README on GitHub
  </Card>
</CardGroup>