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

# Record User Sessions

> Install the Recording SDK and capture your first session to see how people interact with your product.

## Before You Begin

You need:

* A Confidence account with Recordings enabled
* A browser client secret for the environment you want to record
* Permission to create or edit a recording policy
* A recording policy with an active rule for your client. See [recording rules](/docs/capabilities/recordings/recording-rules.md).

Use the **Recording Admin** role for a person who must set up and operate Recordings.
This role can view and delete recordings and create, view, and edit recording policies
and rules. It does not grant access to browser client secrets.

For least-privilege access, use the narrower Recording Reader and Recording Policy
roles. Account Owner, Admin, and Super Admin can also manage recording policies.
Creator or Recording Policy Creator can create and manage a policy that they own.
Editor or Recording Policy Editor can edit an existing policy but cannot create one.

## Set Up the SDK

> [!TIP]
>
> **Do it with AI.** Run `confidence recordings setup` from the
> [Confidence CLI](/docs/start/quickstart-cli.md) to add the SDK to your project. To create the
> recording policy and rule from your AI assistant, follow the
> [Record a Sample of Sessions](/docs/reference/agent/mcp-cookbook.md#record-a-sample-of-sessions) recipe.

**1. Install the package**

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

**2. Review the privacy controls**

The SDK masks input values by default. Review [privacy and data masking](/docs/capabilities/recordings/privacy.md)
before you enable recording in a production environment.

**3. Initialize the recorder**

Call `initSessionRecorder` once, as early as possible when your app loads:

```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',
  },
  debugLogger: message => console.debug(message),
});
```

* `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.md) before capture starts, and you
  can filter recordings by it. Don't add direct personal identifiers, access tokens, or secrets to context.
* `debugLogger` prints `[CSR]` messages while you set up. Remove it before you ship.

The SDK uses automatic mode by default. It starts capture when the session matches an active
recording rule. For every option, see [Recordings SDK (Web)](/docs/reference/sdks/recordings.md).

**4. Verify recording**

Interact with the application, then check the recorder:

```typescript theme={null}
console.log(recorder.isRecording); // true after capture starts
```

A `false` value doesn't always indicate an error. A rule, sample rate, or account capacity can
exclude the session. The debug logger tells you when Confidence skips a session and why. To turn
on logging without changing code, run `sessionStorage.setItem('CSR_DEBUG', 'true')` in the browser
console and reload the page.

**5. Finish the test session**

Close the test tab. If other tabs share the browser session, close those tabs too.
Each tab appears as a separate recording. Allow several minutes after the browser
session ends before you check **Recordings**.

## Customize Recordings

> **[Configure privacy](/docs/capabilities/recordings/privacy.md)**
>
> Mask or block sensitive content before it leaves the browser.

> **[Configure recording rules](/docs/capabilities/recordings/recording-rules.md)**
>
> Control which users and sessions the SDK records.

> **[Add custom data](/docs/capabilities/recordings/custom-data.md)**
>
> Add context, tags, and measurements.

> **[Parameterize routes](/docs/capabilities/recordings/route-parameterization.md)**
>
> Group dynamic application routes.

> **[Integrate feature flags](/docs/capabilities/recordings/feature-flag-integration.md)**
>
> Keep recording and feature flag targeting context consistent.

## Related Resources

> **[Explore recordings](/docs/capabilities/recordings/explore-recordings.md)**
>
> Learn what you can review in the Confidence UI.

> **[Recordings SDK reference](/docs/reference/sdks/recordings.md)**
>
> Review all SDK options and methods.

> **[Troubleshoot recordings](/docs/troubleshooting/recordings.md)**
>
> Diagnose SDK setup and capture problems.