---
title: Session Replay Browser SDK Plugin
description: Use the Session Replay plugin if you instrument your site with Amplitude Browser SDK 2.
product: session-replay
lang: en
last_updated: 2024-09-19
token_estimate: 8546
---
# Session Replay Browser SDK Plugin

> 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`.

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

> **Note:** Session Replay instrumentation
>
> Session Replay isn't on by default, and requires setup beyond the standard Amplitude instrumentation.

The Session Replay Browser SDK plugin adds session recording to a site already instrumented with Amplitude Browser SDK 2. If your site already uses Amplitude instrumentation, use this option. If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). For more information about the Browser SDK, go to [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2).

> **Info:** Session Replay and performance
>
> Session Replay minimizes impact on the performance of the web pages where you install it by:
>
> - Processing content asynchronously through webhooks for efficient compression and optimized bundle sizes.
> - Batching requests and using lightweight compression to reduce network connections and bandwidth.
> - Optimizing DOM processing.

### Bundle size

The Session Replay plugin adds to your application's bundle size.

For current bundle size information, check the [npm package page](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser) or [BundlePhobia](https://bundlephobia.com/package/@amplitude/plugin-session-replay-browser).

### Runtime performance

Session Replay runs asynchronously and processes replay data in the background to avoid blocking the main thread. Performance characteristics include:

- **DOM capture**: DOM snapshot capture typically adds less than 5ms of processing time for each page interaction. Initial page load snapshot capture may take 10-50ms depending on page complexity.
- **Memory usage**: Session Replay stores replay events in memory or IndexedDB (configurable using `storeType`). Memory usage scales with session length and page complexity, typically ranging from 1-10 MB for each active session.
- **CPU impact**: With default settings, Session Replay uses less than 2% of CPU time during normal operation. Session Replay defers compression operations to browser idle periods when `performanceConfig.enabled` is `true` (default).
- **Network bandwidth**: Session Replay compresses replay data before upload, typically reducing payload size by 60-80%. Session Replay batches network requests and sends them asynchronously.

### Performance optimization

To optimize Session Replay performance:

- Enable `useWebWorker`, which moves compression off the main thread and reduces CPU impact.
- Configure `performanceConfig.timeout` to control when deferred compression occurs.
- Set `storeType` to `memory` if you don't need persistence across page reloads, which reduces IndexedDB overhead.

For detailed performance testing results, go to the [Session Replay performance testing blog post](https://amplitude.com/blog/session-replay-performance-testing).

Session Replay captures changes to a page's Document Object Model (DOM), including elements in the shadow DOM. Session Replay then replays these changes to build a video-like replay. For example, at the start of a session, Session Replay captures a full snapshot of the page's DOM. As the user interacts with the page, Session Replay captures each change to the DOM as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original DOM in sequential order to construct the replay. Session replays have no maximum length.

### Defer SDK initialization

Deferring Session Replay initialization until after the page loads eliminates the SDK's contribution to page load metrics. Use this approach when you're measuring load-time metrics like Time to Interactive or Largest Contentful Paint and need zero Session Replay impact. If reducing impact while keeping early initialization is your goal, use the configuration options in [Performance optimization](#performance-optimization) instead.

Initialize Amplitude as usual and defer only the Session Replay plugin using a `load` event listener:

```js
import * as amplitude from "@amplitude/analytics-browser";

// Initialize Amplitude at page load as usual
amplitude.init(API_KEY);

// Load and add the Session Replay plugin only after the page has fully loaded
window.addEventListener('load', async () => {
  const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
  const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
  await amplitude.add(sessionReplayTracking).promise;
});
```

Alternatively, defer until the browser is idle using `requestIdleCallback`. This approach waits for a low-activity moment, reducing contention with other post-load work:

```js
import * as amplitude from "@amplitude/analytics-browser";

amplitude.init(API_KEY);

requestIdleCallback(async () => {
  const { sessionReplayPlugin } = await import('@amplitude/plugin-session-replay-browser');
  const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 0.5 });
  await amplitude.add(sessionReplayTracking).promise;
});
```

Session Replay captures a full DOM snapshot when it initializes. Interactions that occur before initialization don't appear in the replay.

## Prerequisites

The Session Replay Plugin requires that:

1. Your application is web-based.
2. You can provide a device ID to the SDK.
3. Your site uses the Browser 2.0 SDK.

### Supported browsers

Session Replay supports the same set of browsers as Amplitude's SDKs. For more information, refer to [Browser Compatibility](https://amplitude.com/docs/get-started/browser-compatibility).

Session Replay may not support all browser extensions or DOM elements that browser extensions introduce.

Session Replay supports Shadow DOM, but exceptions may exist depending on the frameworks your site uses.

## Quickstart

Install the plugin with npm or yarn.

> **Info:** Unified SDK
>
> If you haven't installed the Browser SDK yet, consider using the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk) instead. The Unified SDK provides a single entry point for all Amplitude features (Analytics, Session Replay, Experiment) and simplifies integration by handling initialization and configuration of all components.

#### npm

```bash
# If you already have Browser SDK installed, install the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save

# OR if you haven't installed Browser SDK yet, use the Unified SDK instead
npm install @amplitude/unified
```

#### yarn

```bash
# If you already have Browser SDK installed, install the Session Replay Plugin
yarn add @amplitude/plugin-session-replay-browser

# OR if you haven't installed Browser SDK yet, use the Unified SDK instead
yarn add @amplitude/unified
```

Configure your application code.

#### Plugin configuration

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

// Create and Install Session Replay Plugin
const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
});
amplitude.add(sessionReplayTracking);

// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);
```

#### Unified SDK

```js
import { initAll } from "@amplitude/unified";

// Initialize Unified SDK with Session Replay configuration
initAll("YOUR_API_KEY", {
  sessionReplay: {
    sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
  },
});
```

You can also add the code directly to the `<head>` of your site. With this method, make sure your application doesn't initialize the Browser SDK elsewhere. If you initialize the Browser SDK more than one time, you may experience mismatches in Device ID or Session ID.

```html
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.47.4-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.36.2-min.js.gz"></script>
<script>
  // sampleRate: 1 records 100% of sessions for initial testing; lower this for production. The SDK default (0) records nothing.
  const sessionReplayTracking = window.sessionReplay.plugin({ sampleRate: 1 });
  window.amplitude.add(sessionReplayTracking);
  window.amplitude.init(API_KEY);
</script>
```

> **Info:**
>
> Session Replay instrumentation happens in the context of an Amplitude Project. Amplitude defines your replay quota at the Organization level. As a result, you can have multiple Session Replay implementations across multiple projects, each with its own sample rate, that pull from the same quota.

> **Tip:** Compatibility with Google Tag Manager
>
> The Session Replay plugin scripts load asynchronously when you add them to the `<head>` tag of your page. As a result, this implementation isn't compatible with Google Tag Manager. For more information, go to [Session Replay Implementation with Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager).

## Configuration

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `number` | No | `0` | Controls how many sessions to select for replay collection. The number is a decimal between 0 and 1, for example `0.4`, representing the fraction of sessions Amplitude randomly selects for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. This field isn't required because Session Replay supports [Remote Configuration](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings) of settings including Sample Rate. |
| `privacyConfig` | `object` | No | `undefined` | Supports advanced masking configurations with CSS selectors. |
| `applyBackgroundColorToBlockedElements` | `boolean` | No | `false` | If true, applies a background color to blocked elements for visual masking. This helps you see which elements Session Replay blocks from capture. |
| `debugMode` | `boolean` | No | `false` | Adds an additional debug event property to help debug instrumentation issues (such as mismatching apps). Recommended only for debugging initial setup, not for production. |
| `serverZone` | `string` | No | `US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects in the EU data center. |
| `configServerUrl` | `string` | No | `undefined` | The endpoint URL to fetch remote configuration. If provided, it overrides the default server zone configuration. |
| `trackServerUrl` | `string` | No | `undefined` | The endpoint URL to send session replay data. If provided, Amplitude forwards requests from the SDK there instead of to the default Session Replay endpoint. |
| `shouldInlineStylesheet` | `boolean` | No | `true` | If true, Session Replay stores the contents of inlined stylesheets. During replay, Session Replay uses the stored stylesheet instead of fetching it remotely. This prevents replays from appearing broken due to missing stylesheets. Inlining stylesheets may not work in all cases. If undefined, Session Replay inlines stylesheets. |
| `storeType` | `string` | No | `idb` | How Session Replay stores replay events. `idb` uses IndexedDB to persist replay events when Session Replay can't send all events during capture. `memory` stores replay events only in memory, so events are lost when the page closes. If IndexedDB is unavailable, the system falls back to memory. |
| `performanceConfig.enabled` | `boolean` | No | `true` | If enabled, Session Replay defers event compression to occur during the browser's idle periods. |
| `performanceConfig.timeout` | `number` | No | `undefined` | Optional timeout in milliseconds for the requestIdleCallback API. If specified, this value sets a maximum time for the browser to wait before running the deferred compression task, even if the browser isn't idle. |
| `useWebWorker` | `boolean` | No | `false` | Uses a web worker to compress replay events. This improves performance by moving compression off the main thread. |

### API endpoints

The browser SDK and plugin use the following endpoints. Select the region that matches your Amplitude project.

| Purpose | US | EU |
| --- | --- | --- |
| Replay data ingestion | `https://api-sr.amplitude.com/sessions/v2/track` | `https://api-sr.eu.amplitude.com/sessions/v2/track` |
| Remote configuration | `https://sr-client-cfg.amplitude.com/config` | `https://sr-client-cfg.eu.amplitude.com/config` |

If you set up a domain proxy, forward requests to these endpoints. Override the defaults with `trackServerUrl` and `configServerUrl`.

#### Alternative API endpoints

The browser SDK network guidance also includes the following endpoint family. For an implementation that sends requests to these addresses, include the corresponding domains in your proxy and CSP configuration.

| Purpose | US | EU |
| --- | --- | --- |
| Replay data ingestion | `https://api-secure.amplitude.com/sessions/track` | `https://api.eu.amplitude.com/sessions/track` |
| Remote configuration | `https://api-secure.amplitude.com/sessions/config` | `https://api.eu.amplitude.com/sessions/config` |

### Track default session events

Session Replay enables session tracking by default. This ensures Session Replay captures Session Start and Session End events. If you didn't capture these events before you implement Session Replay, expect an increase in event volume. For more information about session tracking, go to [Browser SDK 2.0 | Tracking Sessions](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-sessions).

#### SDK configuration

Use the Browser SDK configuration to implicitly enable session tracking.

```js
amplitude.init(API_KEY, USER, {
  autocapture: {
    sessions: true,
  },
});
```

#### Plugin configuration

Disable all default tracking by the Browser SDK. In this case, the plugin enables default session tracking.

```js
amplitude.init(API_KEY, USER, {
  autocapture: false,
});
```

> **Info:** Session Start and Session End events
>
> Starting with plugin version 1.12.1, Session Replay no longer captures `Session Start` and `Session End` events by default. To enable capture of these events, set `forceSessionTracking: true`:
>
> ```js
> const sessionReplayTracking = window.sessionReplay.plugin({
>   forceSessionTracking: true, // Enable capture of Session Start and Session End events
>   sampleRate: 1, // 100% sample rate, should reduce for production traffic.
> });
> ```
>
> Amplitude requires at least one event in any captured session to enable playback of the replay.

### Mask on-screen data

The Session Replay SDK offers three ways to mask user input, text, and other HTML elements.

| Element | Description |
| --- | --- |
| `<input>` | Session Replay masks all text input fields by default. When a user enters text into an input field, Session Replay captures asterisks in place of text. To unmask a text input, add the class `.amp-unmask`. For example: `<input class="amp-unmask">`. |
| text | To mask text within non-input elements, add the class `.amp-mask`. For example, `<p class="amp-mask">Text</p>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the class `.amp-block`. For example, `<div class="amp-block"></div>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |

Configure Light, Medium, or Conservative masking and remote overrides in [Session Replay privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay). Remote settings take precedence when they conflict with SDK settings.

Specify elements to block or mask in the `privacyConfig` object during configuration.

```js
// This configuration blocks .no-track and #ads, sets the default mask level,
// and defines the mask and unmask selectors.
await sessionReplay.init(AMPLITUDE_API_KEY, {
  privacyConfig: {
    blockSelector: ['.no-track', '#ads'],
    defaultMaskLevel: 'medium',
    maskSelector: ['.sensitive-data', '.user-email'],
    unmaskSelector: ['.public-info', '#main-content']
  }
}).promise;
```

#### CSS selectors

Session Replay's configuration supports many types of [CSS Selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors). Specify an element tag (`h1` or `textarea`), a class name (`.hidden`) or a data attribute.

Data attributes may be useful if your class names change often due to hashing. To use data attributes, add a custom attribute like `data-amp-unmask` or `data-amp-mask` to any HTML element. For example, `<textarea data-amp-unmask></textarea>`, then enclose the attribute in square brackets when you specify the selector, `[data-amp-unmask]`.

> **Note:** Remote configuration
>
> If you enable remote configuration and it fails to load, Session Replay doesn't capture any sessions. This prevents capture without the privacy settings you define in the Admin interface.

### User opt-out

The Session Replay plugin follows the Browser SDK's `optOut` setting and doesn't support user opt-outs on its own.

### Content Security Policy (CSP)

If your web application uses a strict Content Security Policy, allow the domains your implementation uses in [API endpoints](#api-endpoints).

#### Required CSP directives

Add `script-src` for CDN loading, `connect-src` for ingestion and remote configuration, and `worker-src` if you enable `useWebWorker`.

#### CSP directives reference

| Directive | Domain | Requirement |
| --- | --- | --- |
| `script-src` | `https://cdn.amplitude.com` | Required when loading the browser SDK or plugin from Amplitude's CDN. |
| `connect-src` | `https://api-sr.amplitude.com` and `https://sr-client-cfg.amplitude.com` | US replay ingestion and remote configuration. |
| `connect-src` | `https://api-sr.eu.amplitude.com` and `https://sr-client-cfg.eu.amplitude.com` | EU replay ingestion and remote configuration when `serverZone: "EU"`. |
| `connect-src` | `https://api-secure.amplitude.com` | Required for implementations that use the alternative US API endpoints. |
| `connect-src` | `https://api.eu.amplitude.com` | Required for implementations that use the alternative EU API endpoints. |
| `worker-src` | `blob:` | Required if you enable `useWebWorker` for replay event compression. |

#### Example CSP header

For US ingestion and remote configuration:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.amplitude.com https://sr-client-cfg.amplitude.com; worker-src 'self' blob:;
```

For EU ingestion and remote configuration:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-sr.eu.amplitude.com https://sr-client-cfg.eu.amplitude.com; worker-src 'self' blob:;
```

For an implementation using the alternative US endpoints:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api-secure.amplitude.com; worker-src 'self' blob:;
```

For an implementation using the alternative EU endpoints:

```text
Content-Security-Policy: script-src 'self' https://cdn.amplitude.com; connect-src 'self' https://api.eu.amplitude.com; worker-src 'self' blob:;
```

If you specify custom endpoints with `configServerUrl` or `trackServerUrl`, add those domains to `connect-src` instead of the corresponding default domains.

### EU data residency

Session Replay is available to Amplitude customers who use the EU data center. Set the `serverZone` configuration option to `EU` during initialization. For example:

```js
// For European users, set the serverZone to "EU"
await sessionReplay.init(AMPLITUDE_API_KEY, {
  serverZone: "EU", // [tl! ~~]
}).promise;
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. If you used Amplitude's new account snippet to instrument, sample rate defaults to `1` (100% of sessions) for easier testing. Update the sample rate from the [Session Replay settings page](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings) or use the `sampleRate` configuration option to set the percentage of total sessions that Session Replay captures. For example:

```js
// This configuration samples 1% of all sessions
await sessionReplay.init(AMPLITUDE_API_KEY, {
  sampleRate: 0.01,
}).promise;
```

For manual and dynamic sampling, quota planning, and remote-setting precedence, go to [Configure Session Replay sampling](https://amplitude.com/docs/session-replay/configure-sampling).

### Disable replay collection

After you enable Session Replay, it runs on your site until either:

- The user leaves your site.
- You call `amplitude.remove(sessionReplayTracking.name)`.

> **Note:**
>
> These examples assume you use the variable `sessionReplayTracking` in your initialization code.

Call `amplitude.remove('sessionReplayTracking')` before a user navigates to a restricted area of your site to disable replay collection while the user is in that area.

To restart replay collection, call `amplitude.add(sessionReplayTracking)` to re-add the plugin.

> **Note:**
>
> `amplitude.add()` takes an object of type `Plugin` as a parameter, and `amplitude.remove()` takes a string as a parameter, which is the name of the plugin you want to remove.

> **Note:**
>
> Always wait for `amplitude.add()` to finish before you call `amplitude.remove()`. If you don't, you may get an error in the console: `TypeError: Cannot read properties of undefined (reading 'teardown')`. Use the `promise` property to do this, as shown in either of these examples:
>
> ```js
> await amplitude.add(sessionReplayTracking).promise;
> await amplitude.remove(sessionReplayTracking.name).promise;
> ```
>
> ```js
> const addPromise = amplitude.add(sessionReplayTracking).promise;
> addPromise.then(() => {
>   amplitude.remove(sessionReplayTracking.name).promise;
> });
> ```

You can also use a feature flag product like Amplitude Experiment to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, and add it to your initialization logic:

```js
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";

// Your existing initialization logic with Browser SDK
amplitude.init(API_KEY);

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  const sessionReplayTracking = sessionReplayPlugin({
    sampleRate: 0.5,
  });
  amplitude.add(sessionReplayTracking);
}
```

## Data retention

Session Replay uses Amplitude tools and APIs for privacy and deletion requests. Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For default retention, extended retention, and the effective date of retention changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#browser-and-react-native-plugin-retention).

### DSAR API

The [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api) describes the metadata the DSAR API returns.

### Data deletion

For user and project deletion behavior, go to [Session Replay data deletion](https://amplitude.com/docs/session-replay/replay-data-lifecycle#data-deletion).

### Bot filter

For bot filtering and property-filter restrictions, go to [Session Replay bot filtering](https://amplitude.com/docs/session-replay/replay-data-lifecycle#bot-filter).

## Session Replay storage

Session Replay doesn't set cookies on the user's browser. Instead, it relies on a browser storage option called [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) by default. This option enables continuous replay collection during a session in which the user navigates browser tabs or closes and reopens a tab. The SDK cleans up the data it stores in IndexedDB and shouldn't impact the user's disk space.

If the environment doesn't support IndexedDB, Session Replay falls back to an in-memory storage option. In-memory storage is less durable and data is lost  when the user closes their browser window. Set the config option `storeType` to `'memory'` to force in-memory storage.

If a user opts out of all cookies on your site, use the `optOut` configuration option to disable replay collection for that user.

### IndexedDB best practices

To ensure that IndexedDB is initialized and working properly:

- Review CSP headers to ensure they're not overly restrictive. Ensure `default-src` and `script-src` directives allow necessary sources.
- Perform IndexedDB operations within the same origin. Cross-origin restrictions can block IndexedDB operations.
- Confirm that users use a modern browser that supports IndexedDB. Amplitude recommends the latest versions of Chrome, Firefox, Safari, Edge, or Opera.

### Cookies

Session Replay doesn't use cookies directly, and has no impact on cookie size. [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) uses cookies for session management.

## Known limitations

Note the following limitations as you implement Session Replay:

- Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  - You instrument your marketing site and web application as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on the marketing site and logs in to the web application.
  - Amplitude captures both sessions.
  - The replay for each session appears in the host project.
- Session Replay can't capture the following HTML elements:

  - Canvas.
  - WebGL.
  - `object` tags including plugins like Flash, Silverlight, or Java. Session Replay supports `object type="image"`.
  - Lottie animations.
  - Cross-origin `<iframe>` elements that don't load the Session Replay SDK with `crossOriginIframes.enabled: true` (for example, third-party embeds like Stripe or Google Maps). To capture first-party cross-origin iframes, go to [Cross-origin iframe recording](https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes).
  - Assets that require authentication, like fonts, CSS, or images.
- Session Replay isn't compatible with ad blocking software.

### Multiple Amplitude instances

Session Replay supports attachment to a single instance of the Amplitude SDK. If your application uses more than one instance, make sure to start Session Replay on the instance that most relates to your project.

```html
<script>
 const sessionReplayTracking = window.sessionReplay.plugin();
  const instance = window.amplitude.createInstance();
  instance.add(sessionReplayTracking);
  instance.init(API_KEY);
<script>
```

## Troubleshooting

For missing, incomplete, or unavailable replays, go to [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting). For ingestion statuses, use the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

### CSS styling doesn't appear in a replay

Session Replay stores references to CSS files and other static assets on your site and uses those references to reconstruct a replay. If the files move or require authentication, Amplitude may be unable to load them during playback:

- Assets on your site move or change name. This can happen when you deploy a new version of your application.
- Assets on your site are behind access controls that prevent Amplitude from fetching them.

To help resolve CSS loading issues:

- Ensure your domain is publicly accessible. If you work in a local environment, Amplitude may not have access to assets stored on `localhost`.
- Your CDN should keep track of old stylesheets for older replays. If the content of the same stylesheet changes over time, try to append a unique string or hash to the asset URL. For example, `stylesheet.css?93f8b89`.
- Add `app.amplitude.com` or `app.eu.amplitude.com` to the list of domains that your server's CORS configuration permits.
- Make external stylesheets accessible to Session Replay. To ensure Session Replay can capture external stylesheets, add the `crossorigin="anonymous"` attribute to the `<link rel="stylesheet">` elements in your code.

  This instructs the browser to load the CSS without sending credentials, which allows cross-origin access to the stylesheet rules. Without this attribute, browsers like Google Chrome block programmatic access to those rules (for example, attempts to read `stylesheet.cssRules` fail).

  These restrictions can prevent Session Replay from capturing styling information, which results in incomplete or broken visual playback.

### Capture sessions contain limited information

Amplitude creates the `[Amplitude] Replay Captured` event automatically when Session Replay captures a session. If you don't see this event in your implementation, replays may not appear correctly in Amplitude's analysis tools like Funnel Analysis, Segmentation, or Journeys charts. You can still find session replays on the Session Replay home page or the user profile page. Contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) if you don't see this event.

If you use a method other than the Browser SDK to instrument your events, consider using the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk/).

### Replay length and session length don't match

In some scenarios, the length of a replay may exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This happens when a user closes their browser or browser tab and `[Amplitude] End Session` occurs, but the Browser SDK and Session Replay plugin haven't yet processed it. When the user visits that page again, the SDK and plugin process the event and send it to Amplitude, along with the replay. You can verify this scenario occurs if you see a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

Session replays may not appear in Amplitude due to:

- Content security policy
- Blocked JavaScript
- No events triggered through the browser SDK in the current session
- Sampling

#### Local development and focus state

The Session Replay SDK and plugin capture only the page that's in focus. When you develop locally with the browser console open, focus states may not work as expected. If you don't see replays in Amplitude, try to enable `debugMode`. In this mode, Session Replay ignores the focus handle and enables extra debugging information.

```js
const sessionReplayTracking = window.sessionReplay.plugin({
 debugMode: true,  
 sampleRate: 1, 
 });
```

#### Content security policy

When you add the Session Replay script to your site, visit a page on which the Session Replay SDK is running, and open your browser's developer tools.

Check for any error messages in the JavaScript console that contain the text `Content Security Policy`. For example, `Refused to connect to 'https://api-secure.amplitude.com/sessions/track' because it violates the document's Content Security Policy`.

To resolve this error, update your site's content security policy to allow connection to Amplitude's APIs.

#### Blocked JavaScript

Browser extensions or network security policy may block the Session Replay SDK. Check your browser's developer tools to see if requests fail, and if so, add an exception for the blocked domains.

#### No events triggered through the browser SDK in the current session

Session Replay requires that at least one event in the user's session has the `[Amplitude] Session Replay ID` property. The [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) `Session Start` and `Session End` events include this property by default. If you instrument your events with any SDK other than the Amplitude Browser SDK 2, use the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk) and ensure you tag your events with the necessary event properties.

For local testing, force a Session Start event to check that Session Replay functions.

1. Open your browser's developer tools, and delete any cookie that begins with `AMP_`.
2. Close developer tools and refresh the page.
3. In Amplitude, the User Lookup Event Stream displays a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button appears for that session.

#### Sampling

The default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information, go to [Sampling rate](#sampling-rate).

#### Some sessions don't include the Session Replay ID property

Session Replay doesn't require that all events in a session have the `[Amplitude] Session Replay ID` property, only that one event in the session has it. The property may be absent when you instrument an event with a source different from the source you connect to Session Replay. For example, your application may send events from a backend source, rather than the Browser SDK.

### Session Replay processing errors

For processing delays, mismatched identifiers, short sessions, incomplete page instrumentation, and expired replays, go to [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting). For retention rules, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#retention-period).