---
title: Browser Session Replay reference
description: "Every public export and option in the Session Replay Browser SDK plugin and standalone SDK, verified against @amplitude/session-replay-browser 1.51.8 and @amplitude/plugin-session-replay-browser 1.36.7, with signatures, types, and defaults."
product: session-replay
lang: en
last_updated: 2026-11-18
token_estimate: 5297
---
# Browser Session Replay reference

This reference documents every public export of `@amplitude/session-replay-browser` (the standalone SDK) and `@amplitude/plugin-session-replay-browser` (the plugin), and every option they accept. It's verified against `@amplitude/session-replay-browser` version `1.51.8` and `@amplitude/plugin-session-replay-browser` version `1.36.7`, which depends on that standalone version. 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`.

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

The standalone SDK exports functions that act on one shared recorder per page. The plugin wraps the standalone SDK: it calls `init()` for you with IDs and settings from Browser SDK 2, and keeps the session ID in sync. The plugin accepts the standalone options, with the exceptions listed in [Plugin options](#plugin-options).

Version markers use the standalone version, with the plugin version in parentheses when it differs.

## Return values

`init()`, `setSessionId()`, and `start()` return an object with a `promise` property, which resolves when the call finishes. `await` the promise before you depend on the result.

```ts
await sessionReplay.init("AMPLITUDE_API_KEY", options).promise;
```

## Plugin

### sessionReplayPlugin

Creates the plugin. `plugin` is an alias of the same function. The script-tag build exposes both as `window.sessionReplay.plugin` and `window.sessionReplay.sessionReplayPlugin`.

```ts
sessionReplayPlugin(options?: SessionReplayPluginOptions): SessionReplayPlugin
```

| Parameter | Type | Description |
| --- | --- | --- |
| `options` | `object` | [Configuration options](#configuration-options), including the [plugin options](#plugin-options). |

```ts
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.1 });
amplitude.add(sessionReplayTracking);
amplitude.init("AMPLITUDE_API_KEY");
```

### SessionReplayPlugin

The class that `sessionReplayPlugin()` returns. You can also construct it with `new SessionReplayPlugin(options)`.

| Member | Description |
| --- | --- |
| `name` | `"@amplitude/plugin-session-replay-browser"`. Pass it to `amplitude.remove()`. |
| `type` | `"enrichment"`. Browser SDK 2 runs the plugin on each event, and the plugin adds the replay ID. |
| `getSessionReplayProperties()` | Same as the standalone [`getSessionReplayProperties`](#getsessionreplayproperties). |
| `start()` | Resumes recording after `stop()`. Returns a `Promise<void>`. Requires plugin 1.34.0 or later. |
| `stop()` | Pauses recording and sends what the SDK recorded. Requires plugin 1.34.0 or later. |
| `sessionReplay` | The standalone functions the plugin uses, such as `flush()` and `evaluateTargetingAndCapture()`. |

The plugin removes `[Amplitude] Session Replay ID` from Identify events, and adds it only to events whose `session_id` is the current session. When the user opts out through Browser SDK 2, the plugin calls `shutdown()`.

## Setup

### init

Starts the standalone SDK: loads the remote configuration, then starts recording if the SDK selects the session. Calling it again re-applies the options.

```ts
init(apiKey: string, options: SessionReplayOptions): { promise: Promise<void> }
```

| Parameter | Type | Description |
| --- | --- | --- |
| `apiKey` | `string` | The project's API key. |
| `options` | `object` | [Configuration options](#configuration-options). Include `deviceId` and `sessionId`. |

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

### shutdown

Stops recording, sends what the SDK recorded, and removes the SDK's page listeners. Call `init()` to start again.

```ts
shutdown(): void
```

### flush

Immediately sends recorded data that's waiting to upload, without waiting for the next batch.

```ts
flush(useRetry?: boolean): Promise<void>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `useRetry` | `boolean` | Retry a failed upload, up to `flushMaxRetries`. Default `false`. |

## Recording

### start

Resumes recording after `stop()`. The sample rate, targeting, and opt-out still apply. Requires 1.49.0 or later.

```ts
start(): { promise: Promise<void> }
```

### stop

Pauses recording and sends what the SDK recorded. The SDK keeps its page listeners, so `start()` can resume. Requires 1.49.0 or later.

```ts
stop(): void
```

### evaluateTargetingAndCapture

Evaluates [targeted capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) conditions, and starts recording if the session matches. Without a targeting configuration for the project, it does nothing. After a session matches, it stays matched. Requires 1.28.0 or later (plugin 1.22.0).

```ts
evaluateTargetingAndCapture(
  targetingParams: {
    event?: Event;
    userProperties?: { [key: string]: any };
    page?: { url?: string };
  },
  isInit?: boolean,
  forceRestart?: boolean,
  forceTargetingReevaluation?: boolean,
): Promise<void>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `targetingParams.event` | `Event` | An analytics event to evaluate, such as `{ event_type: "Checkout Started" }`. |
| `targetingParams.userProperties` | `object` | The user's properties. |
| `targetingParams.page.url` | `string` | The page URL. Defaults to `window.location.href`. |
| `isInit` | `boolean` | Internal. Default `false`. |
| `forceRestart` | `boolean` | Restart recording even when it's already running. Default `false`. |
| `forceTargetingReevaluation` | `boolean` | Evaluate again even when the session already matched. Default `false`. |

```ts
await sessionReplay.evaluateTargetingAndCapture({
  event: { event_type: "Checkout Started" },
});
```

## Sessions

### setSessionId

Starts a new replay for a new session. The SDK sends the previous session's data, fetches the remote configuration again, and restarts recording. Calling it with the current session ID and device ID does nothing.

```ts
setSessionId(sessionId: string | number, deviceId?: string): { promise: Promise<void> }
```

| Parameter | Type | Description |
| --- | --- | --- |
| `sessionId` | `string | number` | The new session ID. Can't contain `/`. String IDs require 1.16.0 or later (plugin 1.10.0). |
| `deviceId` | `string` | Optional. A new device ID. Can't contain `/`. |

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

### getSessionId

Returns the current session ID.

```ts
getSessionId(): string | number | undefined
```

## Replay properties

### getSessionReplayProperties

Returns the event properties that link an event to the current replay. Returns `{}` when the session isn't recording, or before `init()`.

```ts
getSessionReplayProperties(): { [key: string]: boolean | string | null }
```

| Property | Value |
| --- | --- |
| `[Amplitude] Session Replay ID` | `<device ID>/<session ID>`. |
| `[Amplitude] Session Replay Debug` | Only when `debugMode` is `true`. A JSON string with a hash of the API key, to spot events sent to the wrong project. |

```ts
sessionReplay.getSessionReplayProperties();
// { "[Amplitude] Session Replay ID": "device-abc123/1735689600000" }
```

## Types

| Export | Kind | Description |
| --- | --- | --- |
| `SessionReplayOptions` | TypeScript type | Standalone `init()` options. The plugin package re-exports this type, but the plugin accepts a different set. Go to [Plugin options](#plugin-options). |
| `StoreType` | TypeScript type | `"memory" | "idb"`. |
| `AmplitudeSessionReplay` | TypeScript type | The shape of the standalone API. |
| `SendEventsRequest` | TypeScript type | `{ url, method: "POST", headers, body, keepalive }`, passed to `handleSendEvents`. |
| `FetchConfigRequest` | TypeScript type | `{ url, method: "GET", headers, signal? }`, passed to `handleFetchConfig`. |
| `SessionReplaySendEventsHandler` | TypeScript type | `(request: SendEventsRequest) => Promise<Response>`. |
| `SessionReplayFetchConfigHandler` | TypeScript type | `(request: FetchConfigRequest) => Promise<Response>`. |
| `SafeLoggerProvider` | Class | Wraps a logger so a missing method doesn't throw. Standalone only. |

TypeScript types have no runtime value. Import them with `import type`.

## Configuration options

Pass these options to the standalone `init()` or to `sessionReplayPlugin()`. The tables mark options that the plugin doesn't accept as **Standalone only**.

### Capture

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `sampleRate` | `number` | `0` | Fraction of sessions to record, from `0` to `1`. `0` records nothing. A sample rate set in Amplitude replaces this value. The SDK hashes the session ID to decide, so all tabs in a session get the same result. Six decimal places require 1.10.0 or later. |
| `deviceId` | `string` | `undefined` | The device ID your analytics events use. The SDK doesn't record without it. The plugin reads it from Browser SDK 2, and this option overrides it (plugin 1.13.0 or later). |
| `sessionId` | `string | number` | `undefined` | **Standalone only.** The session ID your analytics events use. The SDK doesn't record without it. String IDs require 1.16.0 or later. |
| `optOut` | `boolean` | `false` | **Standalone only.** `true` stops recording for this user. If Browser SDK 2 runs on the page with the same `instanceName`, its opt-out setting wins. |
| `instanceName` | `string` | `"$default_instance"` | **Standalone only.** The Browser SDK 2 instance whose opt-out setting to follow. |
| `userProperties` | `object` | `undefined` | **Standalone only.** User properties for [targeted capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) when `init()` runs. Requires 1.28.0 or later. |

### Privacy

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `privacyConfig.defaultMaskLevel` | `"light" | "medium" | "conservative"` | `"medium"` | What to mask by default. Go to [How masking works](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#how-masking-works). A level set in Amplitude replaces this value. Requires 1.6.0 or later (plugin 1.4.0). |
| `privacyConfig.maskSelector` | `string[]` | `undefined` | CSS selectors for elements whose text the SDK masks. `[data-amp-mask]` always applies. Requires 1.6.0 or later (plugin 1.4.0). |
| `privacyConfig.unmaskSelector` | `string[]` | `[".amp-unmask"]` | CSS selectors for elements to record even when the level masks them. `.amp-unmask` and `[data-amp-unmask]` always apply. Requires 1.6.0 or later (plugin 1.4.0). |
| `privacyConfig.blockSelector` | `string | string[]` | `undefined` | CSS selectors for elements to replace with a placeholder. `.amp-block` and `[data-amp-block]` always apply. |
| `privacyConfig.maskAttributes` | `string[]` | `undefined` | Attribute names to mask on elements whose text the SDK masks. The SDK never masks `style`. Requires 1.34.0 or later (plugin 1.36.0). |
| `privacyConfig.urlMaskLevels` | `{ match: string; maskLevel: string }[]` | `undefined` | **Standalone only.** Mask levels for pages whose URL matches the `match` pattern. The first match wins. Rules set in Amplitude come first. Requires 1.37.0 or later. |
| `applyBackgroundColorToBlockedElements` | `boolean` | `false` | Fills blocked elements with a background color in the replay, so you can see what the SDK blocked. Requires 1.24.0 or later (plugin 1.18.0). |

### Recording

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `shouldInlineStylesheet` | `boolean` | `undefined` | `undefined` or `true` stores stylesheet contents with the recording, so replays don't depend on fetching them later. Set `false` to store only references. Requires 1.8.0 or later (plugin 1.5.0). |
| `inlineImages` | `boolean` | `false` | Stores image data with the recording. Increases upload size. Requires 1.50.0 or later (plugin 1.35.0). |
| `captureAdoptedStyleSheets` | `boolean` | `true` | Records stylesheets that scripts attach with `adoptedStyleSheets`, such as in web components. Requires 1.38.0 or later (plugin 1.28.0). |
| `enableUrlChangePolling` | `boolean` | `false` | Also checks the page URL on an interval, for URL changes that history events miss. Requires 1.27.0 or later (plugin 1.21.0). |
| `urlChangePollingInterval` | `number` | `1000` | Milliseconds between URL checks when `enableUrlChangePolling` is `true`. Requires 1.27.0 or later (plugin 1.21.0). |
| `captureDocumentTitle` | `boolean` | `false` | Records the page title with each URL change. Requires 1.27.0 or later (plugin 1.21.0). |
| `crossOriginIframes.enabled` | `boolean` | Off | Records cross-origin iframes that also load Session Replay with `crossOriginIframes.enabled` set to `true`. Go to [Cross-origin iframe recording](https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes). Requires 1.41.0 or later (plugin 1.30.3). |
| `crossOriginIframes.coordinateChildren` | `boolean` | `true` | Coordinates recording with child iframes. Requires 1.41.0 or later (plugin 1.30.3). |
| `fullSnapshotIntervalMs` | `number` | `undefined` | **Standalone only.** Milliseconds between full snapshots of the page. When unset, the SDK takes a full snapshot only at the start. Requires 1.42.1 or later. |
| `eagerFullSnapshotSend` | `boolean` | `false` | Uploads the first full snapshot right away instead of with the next batch. Requires 1.45.0 or later (plugin 1.32.0). [Default changed in 1.46.0](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes#1460). |
| `captureFullSnapshotOnFocus` | `boolean` | `false` | Takes a full snapshot when the window gains focus. Requires 1.45.0 or later (plugin 1.32.0). |

### Delivery

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `serverZone` | `"US" | "EU"` | `"US"` | **Standalone only.** The data center. `"EU"` sends to `api-sr.eu.amplitude.com` and `sr-client-cfg.eu.amplitude.com`. The plugin reads `serverZone` from Browser SDK 2. |
| `trackServerUrl` | `string` | `undefined` | URL for replay uploads, such as a proxy. Replaces the server-zone endpoint. Requires 1.18.0 or later (plugin 1.11.0). |
| `configServerUrl` | `string` | `undefined` | URL for remote configuration. Replaces the server-zone endpoint. The plugin falls back to the Browser SDK 2 remote configuration URL. Requires 1.18.0 or later (plugin 1.11.0). |
| `storeType` | `"memory" | "idb"` | `"memory"` | Where unsent data waits. `"idb"` keeps it in IndexedDB across page loads, and falls back to memory when IndexedDB is unavailable. [Default changed in 1.42.0](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes#1420). |
| `flushMaxRetries` | `number` | `2` | **Standalone only.** Number of retries for a failed upload. Values above `2` become `2`. The plugin reads this value from Browser SDK 2, with the same limit. |
| `flushIntervalConfig.minIntervalMs` | `number` | `1000` | First upload interval, in milliseconds. The interval grows after each batch. Minimum `100`. Requires 1.44.0 or later (plugin 1.31.0). [Default changed in 1.46.0](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes#1460). |
| `flushIntervalConfig.maxIntervalMs` | `number` | `10000` | Longest upload interval, in milliseconds. Accepts `Infinity`. Requires 1.44.0 or later (plugin 1.31.0). |
| `sendTimeoutMs` | `number` | `10000` | Milliseconds before an upload request times out and counts as a retryable failure. `0` or less turns the timeout off. Requires 1.45.0 or later (plugin 1.32.0). |
| `enableTransportCompression` | `boolean` | `true` | **Standalone only.** Compresses uploads with gzip when the browser supports `CompressionStream`. Set `false` only to debug. Requires 1.44.1 or later. |
| `maxPersistedEventsSizeBytes` | `number` | `6000000` | Largest batch, in bytes, before the SDK closes and uploads it. From `1000` to `8000000`. Requires 1.45.0 or later (plugin 1.32.0). |
| `maxSingleEventSizeBytes` | `number` | `9000000` | Largest single recorded change, in bytes. The SDK drops larger ones and logs a warning. From `1000` to `10000000`. Requires 1.45.0 or later (plugin 1.32.0). |
| `handleSendEvents` | `(request: SendEventsRequest) => Promise<Response>` | `undefined` | Sends uploads with your code. The SDK still decides when to retry. Requires 1.47.0 or later (plugin 1.33.0). |
| `handleFetchConfig` | `(request: FetchConfigRequest) => Promise<Response>` | `undefined` | Fetches remote configuration with your code. Requires 1.47.0 or later (plugin 1.33.0). |

### Performance

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `useWebWorker` | `boolean` | `true` | Compresses uploads in a web worker, off the main thread. The worker starts from a `blob:` URL, so a Content Security Policy needs `worker-src blob:`. Requires 1.30.0 or later (plugin 1.24.0). [Default changed in 1.46.0](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes#1460). |
| `experimental.useWebWorker` | `boolean` | `undefined` | Deprecated. Use `useWebWorker`. |
| `performanceConfig.enabled` | `boolean` | `true` | Serializes recorded changes when the browser is idle. Requires 1.14.0 or later (plugin 1.7.0). |
| `performanceConfig.timeout` | `number` | `2000` | Longest wait, in milliseconds, for idle time before the SDK serializes anyway. Requires 1.14.0 or later (plugin 1.7.0). |
| `performanceConfig.mergeMutations` | `boolean` | `true` | Combines page changes that happen close together before upload. Requires 1.39.0 or later (plugin 1.32.0). [Default changed in 1.46.0](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes#1460). |
| `performanceConfig.interaction.timeoutMs` | `number` | `undefined` | Time limit, in milliseconds, for building the selector of a clicked element. When unset, there's no limit. Requires 1.30.0 or later (plugin 1.25.0). |
| `performanceConfig.interaction.maxNumberOfTries` | `number` | `10000` | Most attempts when building the selector of a clicked element. Requires 1.30.0 or later (plugin 1.25.0). |
| `performanceConfig.interaction.threshold` | `number` | `1000` | Element-count threshold for selector building. Requires 1.30.0 or later (plugin 1.25.0). |

Setting `performanceConfig` replaces the whole default object. If you set only `timeout`, also set `enabled: true`.

### Logging and debugging

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `logLevel` | `number` | Upload errors only | **Standalone only.** `0` none, `1` error, `2` warn, `3` verbose, `4` debug. Without it, the SDK logs upload warnings but not recording decisions. The plugin uses the Browser SDK 2 `logLevel`. |
| `loggerProvider` | `object` | Console logger | **Standalone only.** A logger with `log`, `warn`, `error`, `debug`, `enable`, and `disable` methods, to send SDK messages somewhere else. The plugin uses the Browser SDK 2 `loggerProvider`. |
| `debugMode` | `boolean` | `false` | Adds `[Amplitude] Session Replay Debug` to the replay properties, to spot events sent to the wrong project. Use it only during setup. |

### Plugin options

These options exist only on `sessionReplayPlugin()`.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `forceSessionTracking` | `boolean` | `false` | Turns on Browser SDK 2 Session Start and Session End events, even when `autocapture` turns them off. Plugin versions before 1.12.1 turned this on by default. |
| `customSessionId` | `(event: Event) => string | undefined` | `undefined` | Returns the session ID to record under, for each Browser SDK 2 event. When set, the plugin ignores the Browser SDK 2 session ID. |

The plugin reads `sessionId`, `optOut`, `serverZone`, `instanceName`, `logLevel`, `loggerProvider`, and `flushMaxRetries` from Browser SDK 2, and doesn't accept them as plugin options. It doesn't accept `privacyConfig.urlMaskLevels`, `fullSnapshotIntervalMs`, `enableTransportCompression`, or `userProperties`.

### Settings managed in Amplitude

The SDK reads these settings only from the remote configuration, and ignores values in code:

- Interaction capture (`interactionConfig.enabled`, `batch`, `trackEveryNms`). The `interactionConfig.ugcFilterRules` you set in code apply only when the project also has interaction settings in Amplitude. Go to [Configure UGC filter rules](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules).
- Console and network log capture (`loggingConfig`).
- A minimum session length before upload.
- Targeting conditions. Go to [Capture targeted sessions](https://amplitude.com/docs/session-replay/targeted-replay-capture).

The configuration types also include options from the shared Amplitude SDK core, such as `flushQueueSize`, `serverUrl`, and `transportProvider`. Session Replay ignores them.

