---
title: Get started with Browser Session Replay
description: "Install Session Replay on a website with the Browser SDK plugin or the standalone SDK, record a test session, confirm the replay in Amplitude, and fix the problems that stop replays from arriving."
product: session-replay
lang: en
last_updated: 2026-11-18
token_estimate: 2955
---
# Get started with Browser Session Replay

- **Package:** `@amplitude/plugin-session-replay-browser` ([npm](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser))
- **Latest version:** 1.37.0
- **Package size:** 41.9 kB gzip

This guide installs Session Replay on a website, records one test session, and confirms the replay in Amplitude. Session Replay is off until you install it and set a sample rate. Each step lists the conditions that commonly stop replays at that step, so you can fix a problem where it happens. For every option, go to [Configuration options](https://amplitude.com/docs/sdks/session-replay/browser/reference#configuration-options). For changes in each release, go to the [Session Replay Browser SDK release notes](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

## Plan availability

Monthly sessions is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

| Plan | Allowance | How to access |
| --- | --- | --- |
| Free | 10,000 | Included in plan |
| Plus | 10,000 | Included in plan |
| Growth | 20,000 | Included in plan. Add-on for Custom. |
| Enterprise | 50,000 | Included in plan. Add-on for Custom. |

Session Replay for web is available on all plans.

_Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Choose a variant

Session Replay for the browser ships in two packages. Install one of them, not both.

| Variant | Use it when | Package |
| --- | --- | --- |
| Plugin | The site sends events with [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/get-started). | `@amplitude/plugin-session-replay-browser` |
| Standalone SDK | The site sends events with another analytics tool, such as Segment or Google Analytics, or with a server. | `@amplitude/session-replay-browser` |

The plugin reads the device ID, session ID, opt-out setting, and server zone from Browser SDK 2. The standalone SDK reads nothing from other tools: you pass it the device ID and session ID that your analytics tool sends with its events. Amplitude uses those IDs to match each replay to the user's events. For the options, go to [Choose a session matching option](https://amplitude.com/docs/session-replay/session-matching).

For a new Amplitude installation, use the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started) (`@amplitude/unified`) instead. It includes Browser SDK 2 and the Session Replay plugin in one package.

## Prerequisites

- An Amplitude project and its API key. Find the key in _Settings > Projects > your project > General_.
- The data center your organization uses: US (default) or EU.
- A Session Replay plan. Your organization shares one replay quota across projects.
- For the plugin, Browser SDK 2 installed on the page. For the standalone SDK, a device ID and session ID from your analytics tool, available in the browser.
- A page served over `http://` or `https://`, in a browser that [Amplitude SDKs support](https://amplitude.com/docs/get-started/browser-compatibility).

## Install the SDK

Choose one installation method for your variant.

#### Plugin (npm)

```bash
npm install @amplitude/plugin-session-replay-browser
```

```ts
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
```

#### Plugin (script tag)

Load Browser SDK 2 first, then the plugin. The plugin script defines `window.sessionReplay.plugin`.

```html
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.49.3-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.37.0-min.js.gz"></script>
```

#### Standalone (npm)

```bash
npm install @amplitude/session-replay-browser
```

```ts
import * as sessionReplay from "@amplitude/session-replay-browser";
```

#### Standalone (script tag)

The script defines `window.sessionReplay`.

```html
<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.52.0-min.js.gz"></script>
```

To serve the script from your own domain, go to [Self-host the browser Session Replay script](https://amplitude.com/docs/session-replay/self-host-browser-script).

### Fix installation problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| `net::ERR_BLOCKED_BY_CLIENT` for the script or upload requests | An ad blocker or privacy extension blocks Amplitude domains. | Bundle the SDK from npm, and send uploads through a [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests). Test in a profile without extensions. |
| `Cannot read properties of undefined (reading 'plugin')`, or `(reading 'init')` (script tag) | Your code runs before the script loads, or a Content Security Policy blocks `cdn.amplitude.com`. | Load the script before code that uses `window.sessionReplay`, and add `https://cdn.amplitude.com` to `script-src`. |

## Initialize the SDK

Set `sampleRate` explicitly. It defaults to `0`, which records no sessions. The examples use `1` to record every session while you test. Lower it before you release, or [set the rate in Amplitude](https://amplitude.com/docs/session-replay/configure-sampling), which overrides the code.

#### Plugin

Add the plugin before you call `init()`, so it records from the first page load.

```ts
amplitude.add(sessionReplayPlugin({ sampleRate: 1 }));
amplitude.init("AMPLITUDE_API_KEY");
```

With the script tag, use the global:

```html
<script>
  window.amplitude.add(window.sessionReplay.plugin({ sampleRate: 1 }));
  window.amplitude.init("AMPLITUDE_API_KEY");
</script>
```

If your project uses the EU data center, set `serverZone: "EU"` in the Browser SDK 2 `init()` options. The plugin reads `serverZone` from Browser SDK 2.

#### Standalone

Pass the device ID and session ID your analytics tool uses for the same user. The SDK records nothing until it has both.

```ts
await sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId: "device-abc123",
  sessionId: 1735689600000,
  sampleRate: 1,
}).promise;
```

When your analytics tool starts a new session, pass the new session ID:

```ts
await sessionReplay.setSessionId(1735693200000).promise;
```

If your project uses the EU data center, add `serverZone: "EU"` to the `init()` options.

Initialize Session Replay only in browser code. With server-side rendering, initialize it from a client entry point or an effect, not from code that also runs on the server.

### Fix initialization problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Debug log: `Opting session <id> out of recording due to sample rate.` | `sampleRate` is `0` (the default), or the rate didn't select this session. | Set `sampleRate: 1` while you test. Check the rate in [Session Replay settings](https://amplitude.com/docs/session-replay/configure-sampling), which overrides the code. |
| Debug log: `Session <id> not being captured due to capture being disabled for project or because the remote config could not be fetched.` | The SDK couldn't load its remote configuration, or capture is off for the project. Session Replay doesn't record without it. | Allow `sr-client-cfg.amplitude.com` (or `sr-client-cfg.eu.amplitude.com`) in `connect-src` and in any proxy or firewall. Check that capture is on in [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings). |
| Debug log: `Session is not being recorded due to lack of session id.` (or `device id`) | Standalone only. `init()` didn't receive a `sessionId` or `deviceId`. | Pass both to `init()`. Read them from your analytics tool after it initializes. |
| Debug log: `Opting session <id> out of recording due to optOut config.` | Opt-out is on: the Browser SDK 2 `optOut` setting for the plugin, or the `optOut` option for the standalone SDK. | Opt the user back in, or test in a fresh browser profile. |
| Uploads go to `api-sr.amplitude.com` for a project in the EU data center | `serverZone` isn't set to `EU`. | Set `serverZone: "EU"` for EU projects. Omit it for US projects. |

To see these log lines, [turn on debug logging](https://amplitude.com/docs/sdks/session-replay/browser/verify-replays#turn-on-debug-logging).

## Record a test session

1. Open a page where Session Replay runs.
2. Click, type, and scroll for about a minute. Navigate to a second page if your site has one.
3. Send at least one analytics event during the session. With the plugin, a Browser SDK 2 page view counts. With the standalone SDK, send it from your analytics tool with the same device ID and session ID you passed to Session Replay.

The SDK uploads recorded data in batches while the user interacts, and when the user hides or leaves the page. A page with no activity sends nothing until the next interaction.

### Fix upload problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Console error containing `Content Security Policy` for `api-sr.amplitude.com` | The site's Content Security Policy blocks the upload endpoint. | Add the Session Replay endpoints to `connect-src`. Go to [Allow Session Replay in a Content Security Policy](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#allow-session-replay-in-a-content-security-policy). |
| No requests to `/sessions/v2/track` in the **Network** tab | The SDK didn't select the session for recording, or the page has had no activity since the last batch. | Check the debug log for the reasons in [Fix initialization problems](#fix-initialization-problems), then interact with the page. |
| Debug log: `Session replay event batch rejected due to exceeded retry count` | Uploads failed with a network or server error, and the SDK stopped retrying. | Open the failed request in the **Network** tab. A request blocked by the browser needs a CSP or proxy fix. For a server error, check the API key and `serverZone`. |
| Replays upload, but the replay doesn't open from the user's events | The device ID or session ID on the events differs from the one Session Replay used. | Go to [Check that the replay matches its session](https://amplitude.com/docs/sdks/session-replay/browser/verify-replays#check-that-the-replay-matches-its-session). |

## Confirm a replay in Amplitude

1. In Amplitude, open **User Lookup** and search for the device ID or user ID from your test session.
2. Open the session in the **Activity** tab, and select **Play Session**.
3. Confirm that the replay shows the clicks and page changes you made.

Replays usually appear in Amplitude about five minutes after the session starts. If the replay doesn't appear, follow [Verify replays](https://amplitude.com/docs/sdks/session-replay/browser/verify-replays), which checks each stage between the page and Amplitude.

## Next steps

- Choose what to [mask or block](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#mask-data) before you record real users.
- Lower the [sample rate](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#set-the-sample-rate) for production.
- Allow Session Replay in your [Content Security Policy](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#allow-session-replay-in-a-content-security-policy) or send it through a [proxy](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#send-replays-through-a-proxy).

