# Amplitude Documentation — Session Replay
# Generated: 2026-11-08T01:33:19Z
# Pages included: 55 of 55
# Source: https://amplitude.com/docs/llms.txt
# Product feed: llms-session-replay.txt
> Session Replay setup, privacy, playback, and platform SDK plugins.
> 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`.
================================================================================
# Session Replay
URL: https://amplitude.com/docs/session-replay
Updated: 2026-11-04
================================================================================

# Session Replay

## Plan availability

Monthly sessions and Replay retention vary by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

| Plan | Monthly sessions | Replay retention |
| --- | --- | --- |
| Free | 10,000 | 1 month |
| Plus | 10,000 | 1 month |
| Growth | 20,000 (add-on: Custom) | 1 month (add-on: 1, 3, 6, 9, and 12 months) |
| Enterprise | 50,000 (add-on: Custom) | 1 month (add-on: 1, 3, 6, 9, and 12 months) |

AI-based summaries and Targeted Replay Capture are available as an add-on on the Growth and Enterprise plans.

Create session replay GIFs, Data masking, Find replays via users & events, Frustration analytics, Interesting replays, Replays for A/B testing, Saved filters, Session Replay for mobile, Session Replay for web, and Share session replay timestamps are 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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

Session Replay records user sessions and plays them back alongside the events you track in Amplitude. Use replays to understand the behavior behind a conversion drop, investigate a reported issue, or review a product flow.

Use Session Replay when you need to see how individual users experienced your product. To quantify behavior across many users, use [Analytics](https://amplitude.com/docs/analytics). To see aggregate clicks and scrolls on a page, use [Heatmaps](https://amplitude.com/docs/heatmaps), and to choose between them, go to [Heatmaps vs. Session Replay](https://amplitude.com/docs/heatmaps/heatmaps-vs-session-replay).

**Outcome:** [Start capturing sessions](https://amplitude.com/docs/session-replay/instrument-session-replay)

Add Session Replay to your web or mobile app and record your first sessions.

**Outcome:** [Tie replays to your analytics](https://amplitude.com/docs/session-replay/session-matching)

Choose how replays link to the sessions in your charts: by session ID, event property, or timestamp.

**Outcome:** [Protect what users enter](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay)

Mask sensitive text and inputs, block elements, and respect each user's consent choices.

**Outcome:** [Find the session behind a metric](https://amplitude.com/docs/session-replay/find-replays)

Go from a chart, user profile, or support ticket to the recordings that explain it.

**Outcome:** [Watch every step a user took](https://amplitude.com/docs/session-replay/session-replay-viewer)

Play a recording alongside its event timeline to see what happened at each event.

**Outcome:** [Catch frustration and errors](https://amplitude.com/docs/session-replay/analyze-frustration)

Surface rage clicks and dead clicks, then watch the moments that caused them.

**Outcome:** [Let an agent monitor replays for you](https://amplitude.com/docs/session-replay/monitor-replays-with-an-agent)

Review key flows on a schedule and get friction and drop-off findings in your Agent Inbox, email, or Slack.

## Set up and manage capture

Install capture, link replays to your analytics sessions, and confirm capture works before you roll out to production.

- [Understand Session Replay](https://amplitude.com/docs/session-replay/overview) to learn what it captures and how replays relate to your events.
- [Install Session Replay](https://amplitude.com/docs/session-replay/instrument-session-replay) to add replay capture to your app.
- [Choose a matching option](https://amplitude.com/docs/session-replay/session-matching) to link replays to your analytics sessions.
- [Configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching) when an event property defines your sessions.
- [Configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching) when your events have timestamps but no session IDs.
- [Verify capture](https://amplitude.com/docs/session-replay/verify-capture) to check the installation before a production rollout.
- [Manage capture settings](https://amplitude.com/docs/session-replay/session-replay-settings) to control what each project captures.

## Protect privacy

Control what Session Replay records, and make sure capture follows your users' consent choices.

- [Manage privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) to mask or block sensitive content.
- [Manage user consent](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) to start and stop capture based on consent.

## Find and investigate replays

Go from a metric or a support ticket to the recordings that explain it.

- [Find session replays](https://amplitude.com/docs/session-replay/find-replays) behind a chart, user, or support ticket.
- [Watch a replay](https://amplitude.com/docs/session-replay/session-replay-viewer) with its event timeline.
- [Inspect replay errors](https://amplitude.com/docs/session-replay/inspect-replay-errors) to connect errors to what the user experienced.
- [Analyze frustration signals](https://amplitude.com/docs/session-replay/analyze-frustration) like rage clicks and dead clicks.
- [Monitor replays with an agent](https://amplitude.com/docs/session-replay/monitor-replays-with-an-agent) to review a flow across many replays on a recurring schedule.
- [Use Heatmaps](https://amplitude.com/docs/heatmaps) to analyze clicks and scrolls across many sessions.

### [Contextualize User Experience with Session Replay](https://academy.amplitude.com/contextualize-user-experience-with-session-replay)

Learn how to use Session Replay to understand the experience behind your product metrics.

================================================================================
# Session Replay Browser SDK Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-plugin
Updated: 2026-11-04
================================================================================

# Session Replay Browser SDK Plugin

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

> **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).

To install, add the plugin package, register `sessionReplayPlugin({ sampleRate: 1 })` with `amplitude.add` before `amplitude.init`, then [verify capture](https://amplitude.com/docs/session-replay/verify-capture). The [Quickstart](#quickstart) has the full code.

## 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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## 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:** New to Amplitude? Use the Unified SDK
>
> If you haven't installed the Browser SDK yet, use the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started) (`@amplitude/unified`). It includes Session Replay in a single package alongside Analytics and Feature Experiment. Choose one package entry point rather than installing both.

#### npm

```bash
# New integration: install the Unified SDK (includes Session Replay)
npm install @amplitude/unified

# Existing Browser SDK integration: add the Session Replay Plugin
npm install @amplitude/plugin-session-replay-browser --save
```

#### yarn

```bash
# New integration: install the Unified SDK (includes Session Replay)
yarn add @amplitude/unified

# Existing Browser SDK integration: add the Session Replay Plugin
yarn add @amplitude/plugin-session-replay-browser
```

Configure your application code. Set `sampleRate` explicitly. The default is `0`, which records no sessions. The following examples use `1` to record every session while you test. Lower it before production, or [set the sample rate remotely](https://amplitude.com/docs/session-replay/configure-sampling).

#### Unified SDK

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

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

#### Plugin (existing Browser SDK)

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

// Add Session Replay Plugin before initializing
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("AMPLITUDE_API_KEY");
```

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.49.1-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.36.6-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 the `[Amplitude] Session Replay Debug` event property, which contains a hash of your API key, to help debug instrumentation issues such as mismatched 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('AMPLITUDE_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('AMPLITUDE_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.

### Single-page app navigation

Session Replay records the page URL each time it changes, including changes that don't load a new page. The recorder wraps `history.pushState` and `history.replaceState`, and listens for `popstate` and `hashchange` events. When any of these changes `location.href`, Session Replay records the new URL in the replay.

This includes shallow routing, where the app updates the URL without a route change, such as SvelteKit's `pushState` from `$app/navigation` or the Next.js Pages Router's `router.push(url, undefined, { shallow: true })`. The replay attributes everything after a shallow route change to the new URL. Heatmaps use the URL in `location.href` when each click happens, so clicks after a shallow route change count toward the new URL.

If Session Replay misses URL changes, for example because a script calls history methods that Session Replay didn't wrap, set `enableUrlChangePolling` to `true`. Session Replay then checks `location.href` on an interval instead of watching history events. Set the interval in milliseconds with `urlChangePollingInterval`. The default is `1000`.

```js
const sessionReplayTracking = sessionReplayPlugin({
  enableUrlChangePolling: true,
  urlChangePollingInterval: 1000,
});
```

### 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("AMPLITUDE_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.

## Performance

> **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("AMPLITUDE_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("AMPLITUDE_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.

## Server-side rendering and hydration

Frameworks such as Next.js, Nuxt, SvelteKit, Angular SSR, and React Router render HTML on the server, then hydrate it in the browser. The recorder waits until the document finishes parsing, then takes its full snapshot of the server-rendered HTML. Session Replay records every DOM change the framework makes during hydration as an incremental change, so the replay shows what the user saw at each point.

Session Replay runs only in the browser. Add the plugin and call `init` in client-only code, such as a client entry file, a `useEffect` hook, or an `onMount` callback, not in code that also runs on the server.

## Angular apps

In an [Angular](https://angular.dev/) app that uses [Zone.js](https://angular.dev/api/core/NgZone), add the plugin and call `init` outside the Angular zone, the same way the [Browser SDK 2 Angular guidance](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#initialize-the-sdk) describes. For example, call both in `main.ts` before `bootstrapApplication`:

```ts
// main.ts
import { bootstrapApplication } from "@angular/platform-browser";
import * as amplitude from "@amplitude/analytics-browser";
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";

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

bootstrapApplication(AppComponent, appConfig);
```

The recorder already uses the browser's unpatched `MutationObserver`, so DOM mutation tracking doesn't run through Zone.js. The recorder's event listeners, such as mouse, scroll, and input listeners, do run through Zone.js. If the recorder starts inside the Angular zone, each recorded event triggers Angular change detection.

## 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

#### 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).

================================================================================
# Install Session Replay
URL: https://amplitude.com/docs/session-replay/instrument-session-replay
Updated: 2026-11-05
================================================================================

# Install Session Replay

## 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 mobile and Session Replay for web are 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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

Session Replay records user interactions in your app or site so you can investigate the behavior behind your analytics events. Standard analytics instrumentation alone doesn't capture replays, so you install a Session Replay SDK or plugin for your platform.

Start with your platform's Unified SDK to install Analytics and Session Replay together with shared configuration. Use the installation and replay configuration links below, then [complete setup](#complete-setup) to verify a recording.

## Plan your implementation

Before production capture, decide how to [manage consent](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) and [mask sensitive content](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay). Your SDK guide covers the privacy controls that apply to your platform.

## Install the recommended Unified SDK

Choose your platform, follow its installation and initialization instructions, then configure Session Replay capture:

| Platform | Recommended installation | Replay configuration |
| --- | --- | --- |
| Browser | [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started#install-the-sdk) | [Set Session Replay options](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/instrument-and-configure#use-session-replay) |
| Android | [Android Unified SDK](https://amplitude.com/docs/sdks/analytics/android/unified-sdk/get-started#install-the-sdk) | [Configure Session Replay](https://amplitude.com/docs/sdks/analytics/android/unified-sdk/reference#sessionreplayconfigurationbuilder) |
| iOS | [Unified SDK for Swift](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/get-started#install-the-sdk) | [Configure Session Replay](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/instrument-and-configure#use-session-replay) |
| React Native | [React Native Unified SDK (beta)](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk#install-the-unified-sdk) | [Configure the Unified SDK](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk#configure-the-unified-sdk) |

For Flutter, follow the [Flutter Session Replay standalone SDK guide](https://amplitude.com/docs/sdks/session-replay/session-replay-flutter-standalone-sdk).

## Add replay to an existing integration

Use a plugin when you want to keep your existing Amplitude Analytics SDK installation. Use a standalone SDK when you use another analytics provider.

### Browser alternatives

| Your setup | Implementation guide |
| --- | --- |
| You already use Amplitude Browser SDK 2 | [Browser plugin quickstart](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#quickstart) |
| You use a different analytics provider | [Browser standalone SDK quickstart](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#quickstart) |
| You instrument Amplitude with Google Tag Manager | [Install with Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager) |

### Mobile alternatives

| Platform | With an existing Amplitude Analytics SDK | Without an Amplitude Analytics SDK |
| --- | --- | --- |
| Android | [Android plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin) | [Android standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone) |
| iOS | [iOS plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin) | [iOS standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk) |
| React Native | [React Native plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin) | [React Native standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk) |

If you use Segment's Amplitude (Actions) destination for React Native, follow the [React Native Segment integration](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-segment-integration).

## Third-party integrations

| Analytics provider | Implementation guide |
| --- | --- |
| Segment | [Segment wrapper](https://amplitude.com/docs/sdks/session-replay/session-replay-wrapper-for-segment) to choose the integration path for your site |
| RudderStack | [RudderStack integration](https://amplitude.com/docs/sdks/session-replay/session-replay-rudderstack-integration) |

## Complete setup

After installing your SDK or integration:

1. Configure [privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) and the platform-specific masking controls in your SDK guide.
2. Choose a [session matching option](https://amplitude.com/docs/session-replay/session-matching) to connect replays with analytics events. Default Amplitude sessions match automatically. For event-property session definitions, [configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching). For pipelines without session IDs, [configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching).
3. Set a [sample rate](https://amplitude.com/docs/session-replay/configure-sampling). The SDK default is `0`, which records no sessions, so set a value above `0` in code or in your project's remote settings. Use [targeted capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) if you need conditional capture.
4. [Verify capture](https://amplitude.com/docs/session-replay/verify-capture) with a test session before production rollout.

[Self-hosting](https://amplitude.com/docs/session-replay/session-replay-self-hosting) is optional when you need to serve browser scripts or proxy requests through your own domain.

================================================================================
# Self-host Session Replay SDKs
URL: https://amplitude.com/docs/session-replay/session-replay-self-hosting
Updated: 2026-10-19
================================================================================

# Self-host Session Replay SDKs

Self-hosting serves browser SDK files and routes API calls through your own domain. Use it to avoid requests that ad blockers prevent or to meet requirements for routing data through your infrastructure before it reaches Amplitude.

Choose either or both independent tasks:

| Task | Use when |
| --- | --- |
| [Self-host the browser script](https://amplitude.com/docs/session-replay/self-host-browser-script) | You load the SDK through a `<script>` tag and want to serve the file from your CDN or static server. Bundled npm installations skip this task. |
| [Proxy replay requests](https://amplitude.com/docs/session-replay/proxy-replay-requests) | You want replay ingestion requests, and browser remote configuration requests, to pass through your server. |

The iOS and Android SDKs support a custom URL for replay uploads. The React Native and Flutter SDKs don't support custom proxy URLs. Their `serverZone` option selects Amplitude's US or EU data center, and requests go directly to Amplitude.

## Part 1: Self-host the SDK script

Go to [Self-host the browser Session Replay script](https://amplitude.com/docs/session-replay/self-host-browser-script).

### Get the SDK file

Go to [Get the SDK file](https://amplitude.com/docs/session-replay/self-host-browser-script#get-the-sdk-file) for pinned download examples.

### Serve the file

Go to [Serve the file](https://amplitude.com/docs/session-replay/self-host-browser-script#serve-the-file) to update script tags and caching.

## Part 2: Proxy API calls

Go to [Proxy Session Replay requests](https://amplitude.com/docs/session-replay/proxy-replay-requests).

### How the proxy works

Go to [How the proxy works](https://amplitude.com/docs/session-replay/proxy-replay-requests#how-the-proxy-works) for forwarding and response requirements.

### Analytics SDKs

Go to [Proxy Analytics SDK requests](https://amplitude.com/docs/sdks/analytics/proxy-requests) if your implementation also needs to proxy Analytics traffic.

### Remote config proxy (Browser SDK 2 only)

Go to [Remote config proxy](https://amplitude.com/docs/sdks/analytics/proxy-requests#remote-config-proxy-browser-sdk-2-only) for the separate Browser SDK 2 configuration request.

### Session Replay: Browser (Plugin and Standalone SDK)

Go to [Browser replay proxy configuration](https://amplitude.com/docs/session-replay/proxy-replay-requests#session-replay-browser-plugin-and-standalone-sdk) for ingestion and configuration endpoints.

### Session Replay: Mobile (iOS and Android)

Go to [Mobile proxy setup](https://amplitude.com/docs/session-replay/proxy-replay-requests#session-replay-mobile-ios-and-android) for the iOS and Android custom server URL options.

## Content Security Policy (CSP)

Configure [script hosting CSP](https://amplitude.com/docs/session-replay/self-host-browser-script#content-security-policy) for your file-serving domain and [proxy CSP](https://amplitude.com/docs/session-replay/proxy-replay-requests#content-security-policy-csp) for network endpoints.

================================================================================
# Understand Session Replay
URL: https://amplitude.com/docs/session-replay/overview
Updated: 2026-11-04
================================================================================

# Understand Session Replay

Session Replay records real user sessions in your product and replays them alongside the events you track in Amplitude. Use it to understand why users hesitate, leave a funnel, or encounter problems in a product flow.

Use Session Replay to watch one user's experience. For an aggregate view of where users click, tap, and scroll across many sessions, use [Heatmaps](https://amplitude.com/docs/heatmaps). To compare the two, along with Zoning Insights, go to [Heatmaps vs. Session Replay](https://amplitude.com/docs/heatmaps/heatmaps-vs-session-replay).

Session Replay isn't enabled by default. To start recording, [install Session Replay](https://amplitude.com/docs/session-replay/instrument-session-replay) with an SDK or integration.

## Plan availability

Find replays via users & events, Frustration analytics, Replays for A/B testing, Saved filters, Session Replay for mobile, Session Replay for web, and Share session replay timestamps are available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## What a replay shows

When you [watch a replay](https://amplitude.com/docs/session-replay/session-replay-viewer), you can follow the user's activity alongside an event timeline. Inspect clicks, navigation, and the context around an action to understand what an event count alone can't explain.

[Error analytics](https://amplitude.com/docs/session-replay/inspect-replay-errors) exposes console logs and failed network requests. [Frustration analytics](https://amplitude.com/docs/session-replay/analyze-frustration) highlights rage clicks and dead clicks. Each capability's guide states its SDK requirements.

[Session matching](https://amplitude.com/docs/session-replay/session-matching) connects captured replays with your analytics sessions so you can investigate the behavior behind a chart. If you define sessions with an event property, [configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching). If your analytics pipeline doesn't send session IDs, [configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching). Amplitude doesn't stitch one user's replays across multiple projects.

## When to use Session Replay

- **Improve conversions**: Pair quantitative trends with recordings to form and test hypotheses about a workflow.
- **Diagnose product issues**: Review the session behind a reported bug to understand the user's experience.
- **Identify behavior patterns**: [Create an analytics chart from replay events](https://amplitude.com/docs/session-replay/analyze-events-from-replays) to check whether a session represents a broader trend.
- **Review a new feature**: Watch how customers use a newly launched flow without relying only on surveys.
- **Collaborate on an investigation**: [Share a replay](https://amplitude.com/docs/session-replay/share-replays) and discuss specific moments with teammates.

For a ranked view of issues across sessions, use [Friction Monitor](https://amplitude.com/docs/session-replay/friction-monitor). The [Session Replay Agent](https://amplitude.com/docs/amplitude-ai/session-replay-agent) analyzes recordings at scale to surface friction, navigation patterns, and engagement insights.

## Capture and privacy

[Privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) control which content Amplitude masks or excludes. [Data lifecycle rules](https://amplitude.com/docs/session-replay/replay-data-lifecycle) describe retention, deletion, and privacy requests. SDK references state capture limitations for each platform.

## Open a replay

Find Session Replay in the left-hand sidebar in Amplitude Analytics. [Find session replays](https://amplitude.com/docs/session-replay/find-replays) explains how to open recordings from search, User Look-Up, charts, and your homepage.

================================================================================
# Monitor replays continuously with an agent
URL: https://amplitude.com/docs/session-replay/monitor-replays-with-an-agent
Updated: 2026-10-06
================================================================================

# Monitor replays continuously with an agent

The [Session Replay Agent](https://amplitude.com/docs/amplitude-ai/session-replay-agent) watches your session replays on a recurring schedule and reports the behavioral patterns it finds. The agent samples replays within a funnel or event you choose and analyzes them for friction, navigation, and engagement patterns. It delivers findings with highlight-reel clips to your Agent Inbox, email, or Slack. Product managers, UX designers, and growth teams use it to monitor key flows without watching sessions one at a time.

Use continuous agent monitoring when you want ongoing coverage of a flow across many replays. After the agent flags a session for your review, you can investigate that specific session in the [Session Replay viewer](https://amplitude.com/docs/session-replay/session-replay-viewer).

## Why manual replay review doesn't scale

Watching replays one at a time works well for answering a specific question, but it has limits as a monitoring strategy:

- **Volume**: A busy flow can produce more replays in a day than a team can watch in a week, so manual review covers only a small, often unrepresentative slice.
- **Inconsistency**: Different reviewers notice different things, and review tends to happen only after a metric drops or a customer complains.
- **Anecdotes over evidence**: A single striking replay is hard to weigh against the rest of your traffic without knowing how many sessions share the same pattern.
- **Missed issues**: Reviewers look for the problems they already suspect, so issues nobody thought to check go unnoticed.

## Benefits of monitoring replays with an agent

An agent that reviews replays on a schedule resolves the limits of manually reviewing replays.

### Coverage at scale

During each run, the agent collects a representative sample of replays where your chosen funnel or event occurs, then analyzes them together. You get a cross-session view of how users move through a flow rather than a handful of individual impressions.

### Proactive detection

The agent runs on the frequency (day and time) you configure. Regressions from a release, a redesign, or a third-party change surface in your next report instead of waiting for a support ticket or a dashboard review.

### Fresh analytical angles each run

On scheduled runs, the agent acts like a product manager who explores your data without prior assumptions. It picks a different focus within your scope each time, such as friction detection, user journey mapping, or content engagement analysis. Over successive runs, this rotation covers questions your team might not have thought to ask.

### Quantified, evidence-backed findings

Each finding includes the number and percentage of sessions it affects, the specific UI elements involved, and a highlight reel of clips that show the pattern. You can prioritize by impact and share the clips as evidence, rather than debating anecdotes.

### Recommendations tied to your interface

The agent extracts page HTML and UI component context from sampled sessions, so its recommendations point to specific buttons, forms, and flows in your product. Teams can move from a finding to a concrete fix or experiment idea.

### Findings delivered where your team works

Reports go to your Agent Inbox, email subscribers, or a connected Slack channel. You can [share the agent](https://amplitude.com/docs/amplitude-ai/specialized-agents-overview#share-agents-with-your-team) so stakeholders across product, design, and engineering see the same findings. To investigate a finding or act on it, ask follow-up questions in [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview), which can create cohorts or launch experiments with your approval.

## Agent monitoring compared with other replay tools

Session Replay offers several ways to find problems in replays:

| Approach | Best for |
| --- | --- |
| [Session Replay viewer](https://amplitude.com/docs/session-replay/session-replay-viewer) | Watching a specific user's session to understand exactly what happened. |
| [Analyze frustration](https://amplitude.com/docs/session-replay/analyze-frustration) | Inspecting frustration signals like rage clicks and dead clicks within individual replays. |
| [Friction Monitor](https://amplitude.com/docs/session-replay/friction-monitor) | Ranking dead-click and error-click issues across sessions by impact and routing them. |
| [Session Replay Agent](https://amplitude.com/docs/amplitude-ai/session-replay-agent) | Recurring analysis of a funnel or event, with themed findings and recommendations. |

Agent monitoring complements these tools. Use the agent to identify where to look. Then use the viewer and frustration analysis to examine individual sessions in detail.

## Get the most from agent monitoring

- **Scope the agent to a flow that matters**: Choose a funnel or key event tied to revenue or activation, such as signup, checkout, or a new feature's first use.
- **Add focus instructions**: Tell the agent what to watch for, such as a recent redesign, a new feature, or users who abandon their carts.
- **Run one agent per critical flow**: Separate agents keep each report focused and make findings easier to route to the owning team.
- **Capture enough replays**: The agent can only analyze sessions that Session Replay records. Review your [sampling configuration](https://amplitude.com/docs/session-replay/configure-sampling) or use [targeted replay capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) so the flows you monitor have enough replays.

## Requirements and limitations

The agent requires [Session Replay](https://amplitude.com/docs/session-replay/instrument-session-replay) on your project. It analyzes replays within your retention window, so coverage depends on the replays you capture and keep.

The agent supports web apps, mobile WebView, and in-app browsers. It doesn't support native iOS and Android replays, because those replays don't include the element-level data the agent needs. For full details, refer to the [Session Replay Agent platform compatibility](https://amplitude.com/docs/amplitude-ai/session-replay-agent#platform-compatibility).

To create and configure the agent, refer to [Session Replay Agent](https://amplitude.com/docs/amplitude-ai/session-replay-agent#creating-and-configuring-the-agent).

================================================================================
# Identify user friction with Friction Monitor
URL: https://amplitude.com/docs/session-replay/friction-monitor
Updated: 2026-10-05
================================================================================

# Identify user friction with Friction Monitor

Friction Monitor finds the user experience problems that hurt your product most, ranks them by impact, and routes each one to the team that owns it. It detects friction signals that Amplitude captures during real user sessions, groups matching signals into distinct issues, and links the session replays where each issue happened. Product managers, UX teams, and engineers use Friction Monitor to move from a flood of individual friction signals to a short, prioritized list of problems worth fixing.

Use Friction Monitor when you want a ranked, cross-session view of which UX problems to prioritize. To inspect signals within one user's session, [analyze frustration in a replay](https://amplitude.com/docs/session-replay/analyze-frustration).

## How Friction Monitor works

Friction Monitor turns raw friction signals into a ranked list of issues you can act on. It works in a few stages:

- **Detect and fingerprint signals**: Friction Monitor reads Autocapture data to detect friction signals, then fingerprints each one so it can recognize the same problem across many sessions.
- **Group signals into issues**: It groups matching signals into distinct issues, so a single recurring problem shows up as one issue rather than thousands of separate events.
- **Rank by impact**: Amplitude scores each issue's impact and orders the list so the highest-impact issues surface first. Each assessment includes a short description, an impact score, and recommended actions.
- **Link related replays**: Each issue links to the session replays where it occurred, so you can watch the problem happen in context.
- **Label and route**: Amplitude generates a label for each issue and routes it automatically to the relevant team or owner.

## What Friction Monitor detects

Friction Monitor detects two types of friction signal:

- **Dead clicks**: The [dead-click signal](https://amplitude.com/docs/session-replay/analyze-frustration#frustration-event-types), grouped across sessions into issues.
- **Error clicks**: Clicks that coincide with an error in the session, which often point to a broken or failing interaction.

Amplitude captures these signals through Autocapture, so you don't need to instrument them manually.

## How Amplitude ranks and routes issues

Friction Monitor prioritizes issues by impact and helps you get each one in front of the right people:

- **Impact ranking**: Amplitude ranks issues by their estimated impact so your team can focus on the problems that matter most.
- **AI labels and automatic routing**: Amplitude generates a label for each issue and routes it to the team or owner responsible for that part of the product.
- **Slack notifications**: Friction Monitor sends notifications to Slack so teams learn about new or high-impact issues without checking the dashboard.
- **Linear integration**: You can connect issues to Linear to track fixes in your existing workflow.
- **MCP tools**: Friction Monitor exposes MCP tools so you can query issues by team, owner, and impact from an AI assistant.

## Access requirements

To use Friction Monitor, your account needs:

- Access to the Friction Monitor closed beta. Eligibility applies.
- Amplitude AI features enabled.
- [Autocapture](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#autocapture-replaces-defaulttracking) enabled, with enough event volume for Amplitude to detect and group friction signals.

## Where to find Friction Monitor

Find Friction Monitor in Amplitude under _Experience Analytics > Friction Monitor_. The list view shows your ranked issues, and selecting an issue opens its detail view with the impact assessment and linked replays.

## Limitations

> **Note:**
>
> Friction Monitor detects dead clicks and error clicks. It relies on Autocapture data, so it can't detect friction on interactions that Autocapture doesn't capture. Issue detection and grouping depend on having enough event volume.

================================================================================
# Find funnel friction with Session Replay
URL: https://amplitude.com/docs/quick-guides/find-funnel-friction-with-session-replay
Updated: 2026-10-07
================================================================================

# Find funnel friction with Session Replay

## Why funnels and Session Replay matter

- Stop guessing why a number changed. Watch the experience behind a drop-off percentage.
- Fix the right thing first. Watch a few sessions to tell a repeated problem from a one-off.
- Give your team the same context. Share a replay link so product, design, and engineering can review the same moment.

## Questions Session Replay can answer

- Why are people abandoning checkout or signup?

  Watch people who dropped off at your biggest step. Look for a button that doesn't respond, an error message, or a confusing form.
- Did your latest release break something?

  Watch drop-offs at the same step before and after the release. Look for rage clicks, which are repeated clicks in the same spot. Look for dead clicks, which are clicks on something that does nothing.
- What do people who buy do differently?

  Watch two or three people who converted, meaning they completed the funnel. Then watch two or three who left at the same step. Use the differences to choose your next test.

## Find funnel friction with Session Replay

Start with a funnel you already use, such as Add to Cart, Start Checkout, then Purchase.

1. **Open your existing funnel**

   Check that **Measured as** at the top is set to **Conversion**. Replays only appear for this measure.

2. **Choose the biggest drop-off**

   Click the dropped-off part of the bar at the step where you lose the most people. To compare with people who made it through, click the converted part instead. A small menu opens.

3. **Open the matching replays**

   Click **Watch Session Replays**. The replays show recorded sessions from the people behind that number.

4. **Watch two or three sessions**

   Speed up playback and skip quiet moments. Look for a problem that appears more than once: repeated clicks, an error, or someone going back and forth.

5. **Share what you found**

   Copy the replay link and send it to the teammate who can fix the problem. Add one sentence: "People drop off at \[step\] because \[what you saw\]."

> **Note:** Can't open Watch Session Replays?
>
> If **Watch Session Replays** is missing or disabled, check that your funnel uses **Conversion** and a recent date range. Replay availability depends on your organization's [retention period](https://amplitude.com/docs/session-replay/replay-data-lifecycle#retention-period). If you still can't open replays, ask your Amplitude admin whether Session Replay is set up for this project.

## Use Global Agent to review your funnel

Copy the prompt below, then click **Open Amplitude**. Open Global Agent and paste the prompt. Replace the bracketed text with details about your business and project.

```text
In [project name], review my existing funnel [saved funnel URL or name] for [date range]. Use the Conversion measure. Find the step with the biggest drop-off. Analyze two or three available replays of people who left at that step, then compare with two or three who made it through. Look for repeated clicks, errors, confusing forms, or people going back and forth. Summarize repeated problems, include replay links as evidence, and suggest one change to test. Draft a message for my team: "People drop off at [step] because [what you saw]." If you can't access the replays, tell me what is missing and how to continue the review myself.
```

================================================================================
# Find checkout friction before peak traffic
URL: https://amplitude.com/docs/quick-guides/find-checkout-friction-before-peak-traffic
Updated: 2026-11-03
================================================================================

# Find checkout friction before peak traffic

## Fix conversion leaks before holiday traffic multiplies them

- Small issues become expensive fast. A confusing promo, surprise shipping cost, payment error, or broken mobile form can affect far more shoppers once traffic spikes.
- Fix the highest-risk barrier first. Use real shopper evidence to tell a one-off from a repeated problem that costs purchases.
- Give owners proof while there is still time to act. Share the exact shopper moment with the team that can fix it before peak traffic shows the issue at scale.

## Friction points Session Replay uncovers

- Where could you lose the most revenue when traffic peaks?

  Watch the sessions behind your largest cart and checkout drop-off. Look for repeated barriers that affect more shoppers as volume rises.
- Is your promotion helping shoppers buy, or making purchase harder?

  Review sessions from shoppers who use seasonal offers or promo codes. Look for rejected codes, unclear terms, or discounts that are hard to apply before checkout.
- What should you fix before it becomes a peak-season problem?

  Compare shoppers who purchased with shoppers who left at the same step. Focus on the difference most likely to protect completed purchases.

## Uncover your biggest leaks today

Start with a saved funnel you already use for a real outcome, such as a campaign landing page, signup, checkout, upgrade, or support flow. Investigate the step that matters to your question. You don't need to create a purchase funnel, a holiday funnel, or a two-step funnel.

1. **Open a saved funnel you already use**

   Choose any funnel tied to a real business outcome. If you don't have a purchase funnel, you don't need to create one to take this course. To track checkout events for one later, go to [Instrument a checkout funnel](https://amplitude.com/docs/data/sources/instrument-checkout-funnel).

2. **Choose one moment to investigate**

   Select the converted or dropped-off portion of the step where you see an important gap. You don't need a second, preceding step. The step you select is the starting point for Microscope.

3. **Open the matching replays**

   In Microscope, select **Watch Session Replays**. When the funnel uses the **Conversion** measure, you can open replays for people who converted or dropped off at that step. [View Session Replay from a chart](https://amplitude.com/docs/session-replay/find-replays#view-session-replay-from-a-chart).

4. **Watch for repeated friction**

   Review two or three sessions when they're available. Look for what shoppers tried, what failed, and whether the experience differed from people who made it through. Signals include an unresponsive button, a failed form, unclear navigation, repeated clicks, or an error.

5. **Capture the next action**

   Copy the replay link or add the replay to a notebook. Then write one sentence: "Users are dropping because \_\_\_; we should test \_\_\_."

> **Note:** Can't open Watch Session Replays?
>
> If **Watch Session Replays** is missing or disabled, check that your funnel uses **Conversion** and a recent date range. Replay availability depends on your organization's [retention period](https://amplitude.com/docs/session-replay/replay-data-lifecycle#retention-period). If you still can't open replays, ask your Amplitude admin whether Session Replay is set up for this project.

## Use Global Agent to review holiday checkout

Copy the prompt below, then click **Open Amplitude**. Open Global Agent and paste the prompt. Replace the bracketed text with details about your business and project.

```text
Look at my e-commerce purchase funnel [funnel name] for the last [time range]. Find the step where shoppers drop off most, especially between product view, cart, checkout, and purchase. Review Session Replays of shoppers who dropped off and compare them with shoppers who purchased. Identify the top 3 barriers to conversion, including cart abandonment, promo-code issues, shipping or payment friction, and product comparison behavior. Link an example replay for each and recommend the one fix to test before Black Friday and Cyber Monday.
```

================================================================================
# Configure custom session matching
URL: https://amplitude.com/docs/session-replay/configure-custom-session-matching
Updated: 2026-11-04
================================================================================

# Configure custom session matching

Custom session matching connects replays to sessions that your Amplitude project groups by an event property, such as an order ID. Send that property's value to the replay SDK so an event-based search returns the recording of the same activity.

Use this setup when your project has an event-property session definition. If your project uses the default `session_id`, [Amplitude session matching](https://amplitude.com/docs/session-replay/session-matching#match-amplitude-sessions-recommended) works automatically. If your pipeline sends no session IDs, [configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching) instead.

## Prerequisites

### Minimum SDK versions

- Browser SDK Plugin: `@amplitude/plugin-session-replay-browser` version 1.10.0 or later.
- Browser Standalone SDK: `@amplitude/session-replay-browser` version 1.17.0 or later.
- iOS (plugin and standalone): Session Replay for iOS version 0.11.2 or later.
- Android (plugin and standalone): Session Replay for Android version 0.26.4 or later.

### Access and analytics data

- Admin or Manager privileges to edit your project's session definition.
- Analytics events that include a session-defining event property. Use the same property name and session ID value throughout each session.
- The same device ID in your analytics events and replay SDK.

### Constraints

- The session replay ID has the format `<deviceId>/<sessionId>`. Session Replay uses `/` as a delimiter, so neither `deviceId` nor custom session ID values can contain `/`.
- Accepted characters for both `deviceId` and custom session IDs: `a-z A-Z 0-9 _ - . | @ : =`.
- If you need an additional character, contact support.

## Configure the project and matching option

Configure the project before you update the replay SDK:

1. Go to _Settings > Projects_ and select the project that receives your analytics events.
2. Select **Session Definitions**, then **Custom Session Definition**.
3. Under **Session property**, choose the event property that holds your session ID. Enter the confirmation phrase and select **Save**. The [session definition guide](https://amplitude.com/docs/data/sources/instrument-track-sessions#configure-a-custom-session-definition) describes additional timeout and start or end event conditions.
4. Go to _Organization Settings > Session Replay_ and select **Match Amplitude sessions**. This matching option applies to all projects in your organization. Review the [session matching options](https://amplitude.com/docs/session-replay/session-matching#choose-a-matching-option) before changing it.

## Configure the SDK for custom session definitions

Use the instructions for your platform. Pass the same session ID value to Amplitude and Session Replay, and update the replay SDK whenever your custom session changes.

### Browser SDK plugin

Configure the plugin to read the session-defining event property:

1. Install the plugin with the [browser plugin quickstart](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#quickstart).
2. Add a `customSessionId` callback to the plugin configuration. Replace `your_custom_session_id_property` with the event property you selected in _Session Definitions_.
3. Include that property on the analytics events in your custom session. The callback extracts the value from each event.

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

const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: 1,
  customSessionId: (event) => {
    const props = event.event_properties;
    if (!props) {
      return;
    }
    const sessionId = props["your_custom_session_id_property"];
    return sessionId;
  },
});
amplitude.add(sessionReplayTracking);

amplitude.init("AMPLITUDE_API_KEY");
```

The example uses a sample rate of `1` for testing. After verification, restore your [production sample rate](https://amplitude.com/docs/session-replay/configure-sampling).

### Standalone SDK

The browser standalone SDK accepts the custom ID directly through `sessionId`:

1. Install the SDK with the [standalone quickstart](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#quickstart).
2. Read the current session ID from your application or analytics integration. Pass that value as `sessionId` and the analytics device ID as `deviceId` when you initialize Session Replay.
3. Send the same session ID as the event property selected in _Session Definitions_ on your analytics events.
4. Call `setSessionId` with the new value whenever your custom session changes.

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

// Replace these values with IDs from your application or analytics integration.
const deviceId = "your_analytics_device_id";
const sessionId = "your_current_custom_session_id";

await sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId,
  sessionId,
  sampleRate: 1,
}).promise;

// Call whenever your application starts a new custom session.
await sessionReplay.setSessionId("your_next_custom_session_id").promise;
```

The example uses a sample rate of `1` for testing. After verification, restore your [production sample rate](https://amplitude.com/docs/session-replay/configure-sampling). Refer to [Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) for additional options.

### Mobile SDKs

The iOS and Android SDKs accept a string session ID directly instead of a callback:

1. Set `customSessionId` on iOS or call `setCustomSessionId` on Android with your current session ID. For initialization and update examples, use [Custom session IDs on iOS](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#custom-session-ids) or [Custom session IDs on Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone#custom-session-ids).
2. Send the same value as the session-defining event property to Amplitude.
3. Update the replay SDK with the new value whenever your custom session changes.

## Verify custom session matching

1. [Capture a test session](https://amplitude.com/docs/session-replay/verify-capture#capture-a-test-session) with a known custom session ID.
2. Check that the test analytics events include the session-defining property and the expected ID value.
3. [Find the test replay](https://amplitude.com/docs/session-replay/find-replays) using an event from that session. Open the replay and confirm that it shows the expected activity.
4. Start another custom session with a different ID and repeat the check. Confirm that the SDK sends the new value.

If the replay doesn't match, compare the session ID and device ID in the analytics events with the values sent to Session Replay. Check the selected project property and [matching option](https://amplitude.com/docs/session-replay/session-matching#configure-session-matching).

================================================================================
# Configure time-based matching
URL: https://amplitude.com/docs/session-replay/configure-time-based-matching
Updated: 2026-11-04
================================================================================

# Configure time-based matching

Time-based matching connects replays to analytics events using device IDs and overlapping time windows. Use it to find the recording around an event when your pipeline sends timestamps without session IDs, such as events delivered through S3.

If your analytics events include session IDs, use [Amplitude session matching](https://amplitude.com/docs/session-replay/session-matching#match-amplitude-sessions-recommended). If your project groups sessions by an event property, [configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching).

## Prerequisites

- Install the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#quickstart) in your browser application.
- Send the same device ID to Session Replay and on your analytics events.
- Include event timestamps in your analytics pipeline so Amplitude can match events to replay time windows.

## How time-based matching works

Amplitude groups event activity into 30- or 60-minute windows and matches recordings with the same device ID that overlap those windows. The matching has slightly less precision at session boundaries than [matching Amplitude sessions](https://amplitude.com/docs/session-replay/session-matching#match-amplitude-sessions-recommended).

The standalone SDK still needs a `sessionId` to group and upload replay data. With time-based matching, you can generate that ID on the frontend. The ID doesn't need to appear on analytics events, but it must be a valid Unix timestamp in milliseconds for the server to accept the upload.

## Select the matching window

The organization setting applies to all projects in your organization. Review the [matching options](https://amplitude.com/docs/session-replay/session-matching#choose-a-matching-option) before changing it.

1. Go to _Organization Settings > Session Replay_.
2. Select **Time-based event matching**.
3. Select a 30- or 60-minute window.
4. Use the same window size for the frontend replay session ID in the SDK setup below.

## Set a replay session ID

Configure the standalone SDK with a timestamp-based replay ID:

1. Set `WINDOW_MS` to `60 * 60 * 1000` for a 60-minute window, or `30 * 60 * 1000` for a 30-minute window.
2. Round the current time down to the start of that window to generate `sessionId`.
3. Initialize the SDK with that `sessionId`, your project API key, and the same `deviceId` your analytics pipeline sends.
4. Call `setSessionId` when the time window changes. Your application must detect that change; the standalone SDK doesn't manage sessions automatically.

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

const WINDOW_MS = 60 * 60 * 1000;
const now = Date.now();
const sessionId = now - (now % WINDOW_MS);

await sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId: "your_analytics_device_id",
  sessionId,
  sampleRate: 1,
}).promise;

// Run this when your application detects a new time window.
const nextWindowTime = Date.now();
await sessionReplay.setSessionId(nextWindowTime - (nextWindowTime % WINDOW_MS))
  .promise;
```

The example uses a sample rate of `1` for testing. After verification, restore your [production sample rate](https://amplitude.com/docs/session-replay/configure-sampling). Refer to [Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) for additional options.

## Verify time-based matching

1. [Capture a test session](https://amplitude.com/docs/session-replay/verify-capture#capture-a-test-session) and send a known analytics event during the recording.
2. Check that the analytics event and replay use the same device ID, and that the event timestamp falls within the recorded activity.
3. [Find the test replay](https://amplitude.com/docs/session-replay/find-replays) using that event. Open the replay and confirm that it shows the activity around the event.
4. Test across a time-window boundary. Confirm that your application updates `sessionId` and continues to capture replay data.

If matching fails, check the device IDs, event timestamps, and the selected organization window. Use [Session Replay troubleshooting](https://amplitude.com/docs/session-replay/troubleshooting) to diagnose capture and playback failures.

================================================================================
# Verify Session Replay capture
URL: https://amplitude.com/docs/session-replay/verify-capture
Updated: 2026-10-22
================================================================================

# Verify Session Replay capture

Verify Session Replay capture with a test session before you roll out production recording. Check that you can open the replay, associate it with the intended user activity, and apply your privacy settings.

## Prerequisites

- Install the [SDK or integration](https://amplitude.com/docs/session-replay/instrument-session-replay) for your app.
- Configure [session matching](https://amplitude.com/docs/session-replay/session-matching).
- Configure [privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) and any platform-specific masking controls.

## Capture a test session

1. Temporarily set the SDK's `sampleRate` to `1` (100%) to capture all sessions during testing. If you manage sampling through [Session Replay settings](https://amplitude.com/docs/session-replay/configure-sampling), set the rate there to 100%. Follow your SDK's testing instructions for local and remote configuration.
2. Use your app to perform a known sequence of actions and send analytics events through the source connected to Session Replay. Record the test user's ID, the session start time, and the actions you perform.
3. [Find the test replay](https://amplitude.com/docs/session-replay/find-replays) using the test user's ID and a date range that includes the session start time. Replays are generally available five minutes after a session begins.
4. Open the replay in the [viewer](https://amplitude.com/docs/session-replay/session-replay-viewer) and confirm that it shows the actions you recorded in step 2, in the same order.
5. Check that the replay matches the intended analytics session.
6. Review the content you configured to mask or exclude. Confirm that sensitive content doesn't appear in the recording.
7. After confirming capture, session matching, and masking, lower the [sample rate](https://amplitude.com/docs/session-replay/configure-sampling) from `1` (100%) to your intended production rate. Update the SDK configuration or Session Replay settings where you changed the rate for testing.

For browser SDK tests, the [plugin troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#troubleshooting) and [standalone troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting) describe capture and event-association checks.

## Diagnose a failed check

If you can't open the replay or it appears incomplete, inspect the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor). [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting) explains common playback and upload symptoms.

================================================================================
# Find session replays
URL: https://amplitude.com/docs/session-replay/find-replays
Updated: 2026-10-27
================================================================================

# Find session replays

Find a replay by date or behavior in Session Replay search, or open one from a chart, a user's event stream, or your homepage. Use search to compare sessions that meet the same conditions. Use User Look-Up to investigate a session reported by a specific user.

Replays are generally ready to view five minutes after a session begins. If a replay hasn't loaded, follow [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting).

## Plan availability

Find replays via users & events, Replays for A/B testing, and Saved filters are available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Search for a replay

1. Navigate to the Session Replay page to view the list of replays.
2. Select the calendar icon above the list and choose starting and ending dates, or a preset time range of one day, seven days, or 30 days. Date and time filters use the project's timezone.
3. Select **Add Filter** to filter by cohorts, events, event properties, user properties, or session duration. Combine filters to narrow the list.

The results include replays within your selected time frame or matching your filters. The list shows a maximum of 100 replays. Your search generates a unique URL that you can share with your team.

When you exclude a specific property value, search returns replays with a different value and replays with no value for that property.

For the relationship between replay data and analytics events, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching). To narrow results by summary-derived sentiment, [filter replays by sentiment](https://amplitude.com/docs/session-replay/filter-replays-by-sentiment).

## View Session Replay from User Look-Up

Use [User Look-Up](https://amplitude.com/docs/analytics/user-data-lookup) when a user reports a potential bug or you want to investigate their experience.

1. Find the user with their user ID in User Look-Up.
2. Select **Play Session** next to the session in the event stream.

The replay appears to the right of the event stream.

## View Session Replay from a chart

1. Open the Amplitude chart that contains the events you want to investigate.
2. Open [Microscope](https://amplitude.com/docs/analytics/microscope) and select **Watch Session Replays**.
3. Select **Streams with session replays**.

The replay modal shows replays that correspond to the selected chart data point. To watch with event-stream sync, open the standalone replay page from the modal. For playback controls, refer to the [Session Replay viewer](https://amplitude.com/docs/session-replay/session-replay-viewer).

### Availability in Amplitude charts

| Chart | Supported measures and restrictions |
| --- | --- |
| Metric Explorer | Event metrics and session metrics. |
| Event Segmentation | All six measures. |
| Funnel Analysis | The Conversion measure, selected in **Measured as**. Other measures, such as Time to Convert, don't support replays. Replays cover all outcomes at every step, including users who converted and users who dropped off. Select a converted or drop-off data point at any step, open Microscope, then select **Watch Session Replays**. Events appear from oldest to newest. |
| Journeys | Pathfinder and Journey Map visualizations. |
| User Sessions | All six measures. The chart doesn't support replays for [custom-defined sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions). |
| Experiment charts | All Experiment charts. |

In Funnel Analysis, Conversion refers to the chart's measure. It doesn't mean that replays include only users who converted.

Session Replay supports segmentation by users. It doesn't support [account-level reporting](https://amplitude.com/docs/analytics/account-level-reporting).

In a portfolio view, you can view replays from different users and projects. Amplitude doesn't stitch together a user's replays across projects. If a user moves between two projects, Amplitude generates a separate replay for each project.

## View Session Replay from your homepage

Your homepage shows 100 sessions captured over the past seven days. Each session displays its start time, user ID, session length, and country. Select **Play** to open the replay modal.

If the Session Replay widget is missing from a customized [homepage](https://amplitude.com/docs/get-started/amplitude-home-page), reset your homepage, then re-add your customizations to make the widget visible.

================================================================================
# Watch a session replay
URL: https://amplitude.com/docs/session-replay/session-replay-viewer
Updated: 2026-10-22
================================================================================

# Watch a session replay

The Session Replay viewer plays a user's session alongside an event timeline, summary, and profile. Use it to watch how a user navigated or where they got stuck. To choose a recording first, [find a session replay](https://amplitude.com/docs/session-replay/find-replays).

Session Replay supports sessions of any length. When you identify behavior worth measuring across users, [create a chart from replay events](https://amplitude.com/docs/session-replay/analyze-events-from-replays).

## Playback controls

Open a replay and use the player controls to:

- Pause playback
- Skip forward or backward by 10 seconds
- Increase or decrease playback speed
- Skip periods of inactivity
- Expand the replay view

The user's cursor movement appears as a red line. Masked HTML elements appear as asterisks. The player shows the timestamp of the session as it occurred.

## Event-stream synchronization

When you open a replay from your homepage or search, the user's event stream syncs with the recording. Select an event to jump to that point in the session.

Event-stream sync isn't available in the chart replay modal. Open the standalone replay page from the modal to watch with event sync.

Event names with a sparkle icon are names Amplitude generates to describe the user's action. These Autocapture events arrive as `Page Viewed`, `Element Clicked`, and `Element Changed`. Amplitude uses their properties to generate more descriptive names. Select an event to inspect its ingested name and properties.

## Resizable panels

Select the expand icon on a replay to open the expanded viewer. The viewer contains three resizable panels:

- The replay list, on the left
- The video player, in the center
- The side panel, on the right, with the event timeline, summary, profile, and comments

Drag the divider between two panels to resize them. Amplitude saves panel sizes in your browser's local storage and restores them the next time you open the viewer. Select **Reset panel sizes** in the toolbar to restore the defaults.

## Skip Inactivity toggle

Select the tune icon in the player controls to open **Watch Settings**, then toggle **Skip Inactivity**. When on, playback fast-forwards through idle periods. When off, playback includes idle periods at normal speed.

Amplitude saves the preference per user in your browser's local storage. The preference applies when you next open a replay, including embedded carousels and list modals.

- **Default for new users**: Skip Inactivity is on.
- **Scope**: Per user and per browser. Clearing Amplitude site data resets the preference.
- **Embedded players**: Some embedded views override the preference. For example, Agent Analytics replays always skip inactivity.

## Multi-tab behavior

Playback follows the user's focus. When the user switches tabs, the SDK captures a fresh snapshot of the newly focused tab, and playback cuts to it.

The SDK keeps recording background tabs, but playback shows only the focused tab. The event timeline displays events from all tabs, regardless of focus.

You can't manually switch playback to background tabs. If the user switches away from the browser, playback shows an inactive period with the last focused tab.

## Comments

Use **Session Comments** in the side panel to discuss a recording. Follow [Comment on session replays](https://amplitude.com/docs/session-replay/comment-on-replays) to add timestamps, mention teammates, edit comments, and track activity.

## DevTools Network tab

Use the **Network** tab in _DevTools_ to inspect captured requests alongside the recording. Follow [Inspect errors in a session replay](https://amplitude.com/docs/session-replay/inspect-replay-errors#inspect-network-requests) for request details and body-capture requirements.

### Network tab and the Console tab

Use Network and Console together to correlate API calls with JavaScript logs. Follow [View console logs in a replay](https://amplitude.com/docs/session-replay/inspect-replay-errors#view-console-logs-in-a-replay) for console investigation.

================================================================================
# Inspect errors in a session replay
URL: https://amplitude.com/docs/session-replay/inspect-replay-errors
Updated: 2026-10-05
================================================================================

# Inspect errors in a session replay

Inspect console logs and network requests alongside a session replay to identify technical failures during a user's interaction. Use the replay to locate a failure in one session, then analyze error events in charts to measure its impact across users.

## Prerequisites

Error Analytics requires these SDK versions:

| Feature | SDK | Minimum version |
| --- | --- | --- |
| Console errors | [Session Replay Browser SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk) (`@amplitude/session-replay-browser`) | 1.22.4 |
| Console errors | [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) (`@amplitude/plugin-session-replay-browser`) | 1.16.6 |
| Network errors | [Analytics Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) (`@amplitude/analytics-browser`) | 2.24.0 |

Enable [console tracking in Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings#console-tracking) to capture console messages, warnings, and errors.

Error Analytics covers JavaScript console logs, failed network requests and API calls, and runtime JavaScript errors. Network error capture uses the Analytics Browser SDK listed in the requirements table.

## View console logs in a replay

1. [Open a session replay](https://amplitude.com/docs/session-replay/find-replays) from a chart, User Look-Up, or the Session Replay list.
2. Select the console icon to expand the console log view.
3. Select a log entry to jump to that moment in the replay.

The console panel shows logs, warnings, and errors in chronological order alongside the session timeline. Network errors display at the bottom of the replay modal.

## Inspect network requests

Open the **Network** tab in the viewer's _DevTools_ section. Each request shows its URL, HTTP method, status code, and response time. Select a row to open its detail panel.

| Tab | Contents |
| --- | --- |
| Headers | The request URL, HTTP method, status code, and captured request and response headers. |
| Payload | The captured request body. This tab appears only when you configure a `requestBody` capture rule in your SDK settings. |
| Response | The captured response body. This tab appears only when you configure a `responseBody` capture rule in your SDK settings. |
| Timing | When the request started relative to the replay and how long it took, with a waterfall visualization. |

To capture request and response bodies, configure `requestBody` and `responseBody` capture rules in `networkTracking`. Follow [Track network requests](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-network-requests) in the Analytics Browser SDK reference.

Use the Network and Console tabs together to correlate user actions with API calls and JavaScript logs. For example, if checkout fails, check whether the payment API call returned a non-200 status code at that moment.

## Analyze error events

Error events appear in the event stream. You can:

- Use [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) to measure error frequency and trends.
- Include error events in [Funnel Analysis](https://amplitude.com/docs/analytics/charts/funnel-analysis/funnel-analysis-build) to measure their impact on conversion.
- [Filter session replays](https://amplitude.com/docs/session-replay/find-replays#search-for-a-replay) by error events to investigate affected sessions.

================================================================================
# Analyze frustration in session replays
URL: https://amplitude.com/docs/session-replay/analyze-frustration
Updated: 2026-10-05
================================================================================

# Analyze frustration in session replays

Session Replay detects and highlights rage clicks and dead clicks in the session timeline and event stream. Inspect these signals to identify UX problems in a session. For a ranked view of recurring issues across sessions, use [Friction Monitor](https://amplitude.com/docs/session-replay/friction-monitor).

Frustration Analytics requires [Analytics Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) (`@amplitude/analytics-browser`) version 2.24.0 or later. All Session Replay users can use frustration analytics without additional configuration.

## Plan availability

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

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Frustration event types

- **Rage clicks**: Users rapidly click the same element multiple times, usually because something isn't working as expected. A rage click often means a button or link appears interactive but doesn't respond.
- **Dead clicks**: Users click elements that appear clickable but have no functionality, such as non-interactive images styled like buttons or links that lead nowhere.

## View frustration events in replays

1. [Open a session replay](https://amplitude.com/docs/session-replay/find-replays).
2. Find rage click and dead click indicators in the timeline.
3. Select a frustration event to jump to that moment in the replay.

## Measure the impact of frustration

Analyze frustration events with [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) and [Funnel Analysis](https://amplitude.com/docs/analytics/charts/funnel-analysis/funnel-analysis-build) to understand their impact on user behavior and conversion rates.

================================================================================
# Create a chart from replay events
URL: https://amplitude.com/docs/session-replay/analyze-events-from-replays
Updated: 2026-10-05
================================================================================

# Create a chart from replay events

Create an Event Segmentation or Funnel Analysis chart from selected events in a user's event stream to investigate whether behavior in one session reflects a broader trend. [Watch the replay](https://amplitude.com/docs/session-replay/session-replay-viewer) to identify the behavior, then build a chart from the relevant events.

## Select events and create a chart

1. Find the user in [User Look-Up](https://amplitude.com/docs/analytics/user-data-lookup).
2. In the event stream, select up to 10 events you want to review.
3. Select **Create Chart**.
4. Choose an Event Segmentation or Funnel Analysis chart.
5. Select **Create**.

The chart appears in the modal that opens.

================================================================================
# Filter replays by sentiment
URL: https://amplitude.com/docs/session-replay/filter-replays-by-sentiment
Updated: 2026-10-05
================================================================================

# Filter replays by sentiment

Filter replays by positive, negative, or neutral sentiment to investigate the experiences behind users' satisfaction or complaints. Use sentiment for feedback captured in replay summaries. To find sessions by behavior without summary feedback, use [event and property filters](https://amplitude.com/docs/session-replay/find-replays#search-for-a-replay).

Amplitude derives sentiment from user feedback captured during Session Replay Summary generation. Use the sentiment filter to:

- **Understand satisfaction drivers**: Review positive sessions to understand what drives user delight.
- **Investigate issues**: Find negative sessions to understand pain points and bugs.
- **Sample across satisfaction levels**: Combine sentiment filters with other criteria to get representative samples.

## Sentiment categories

The sentiment filter organizes session events into three categories:

| Sentiment | Meaning |
| --- | --- |
| Positive | User indicated satisfaction or a good experience |
| Negative | User indicated dissatisfaction or a problem |
| Neutral | User provided feedback that doesn't clearly indicate satisfaction or dissatisfaction |

## Filter the replay list by sentiment

1. Navigate to _Session Replay > All Replays_.
2. In the filters panel, select **Sentiment**.
3. Choose one or more values:

   - **Positive**
   - **Negative**
   - **Neutral**
4. Click **Save**.

You can combine sentiment filters with user properties, event filters, and replay characteristics like duration. [Watch a matching replay](https://amplitude.com/docs/session-replay/session-replay-viewer) to review the context around the feedback.

> **Note:**
>
> Amplitude only generates sentiment data for replays that have a Session Replay Summary. Replays without summaries don't appear in sentiment filter results.

## Regional availability

You can use the sentiment filter in all regions, including EUDC.

================================================================================
# Measure replay capture
URL: https://amplitude.com/docs/session-replay/measure-replay-capture
Updated: 2026-10-05
================================================================================

# Measure replay capture

Count captured replays with an Event Segmentation chart grouped by replay ID. Use this chart to measure capture volume and trends. For request statuses and delivery failures, use the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

## Count distinct replays

1. Create an [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) chart.
2. Select the `[Amplitude] Replay Captured` event.
3. Group by the `[Amplitude] Session Replay ID` event property.
4. Use `PROPCOUNT(A)` in the formula to count distinct session replay IDs.

`PROPCOUNT(A)` returns the number of distinct values for the property you group by. In this chart, the result is the number of different session replay IDs.

For the event's identity and billing behavior, refer to the [Replay Captured event reference](https://amplitude.com/docs/session-replay/replay-captured-event).

To review your Session Replay quota and retention time frame, navigate to your organization's _Plans & Billing_ page.

================================================================================
# Comment on session replays
URL: https://amplitude.com/docs/session-replay/comment-on-replays
Updated: 2026-10-09
================================================================================

# Comment on session replays

Use the _Session Comments_ tab in the replay viewer to discuss a recording, flag a moment, or hand off an investigation. Comments form a flat thread ordered from oldest to newest, with each comment's author, timestamp, and text. To send a replay without adding a comment, [share its URL](https://amplitude.com/docs/session-replay/share-replays).

Commenting requires the same permission as viewing the replay. Comments support plain text, up to 2,000 characters each.

## Add a comment

1. Open a replay and select **Session Comments** in the side panel.
2. Enter your comment in the text field.
3. To link to a moment, select **Add current timestamp**, or type a timestamp in brackets, such as `[00:10]`. Amplitude inserts a clickable badge that seeks the player to that second.
4. To notify a teammate, type `@` and choose a name from the typeahead. You can mention multiple people in one comment.
5. Select **Post**.

Amplitude notifies mentioned teammates through email, in-app, and Slack. You can also mention external users who have permission to view the replay, which sends them an invite.

## Edit or delete a comment

You can edit and delete only the comments you post.

- To edit your comment, select the edit action, change the text, then save.
- To delete your comment, select the delete action, then confirm.

## Track comment activity

The _All Activity_ tab collects your comment activity across replays. An unread badge marks new activity. Select an item to open its replay and jump to the related comment. Selecting a comment notification opens the replay and highlights the comment.

## Comment and replay persistence

Commenting doesn't bookmark the replay, but it extends the replay's retention. When you comment on a replay, Amplitude keeps it for at least 360 days after the session ends. If your retention period is longer than 360 days, Amplitude doesn't shorten it. Deleting a comment doesn't change the replay's retention.

To keep a replay indefinitely, bookmark it. Go to [Bookmark session replays](https://amplitude.com/docs/session-replay/bookmarkable-session-replays). Commenting on a bookmarked replay doesn't change its retention.

Comments persist after the replay's retention window expires. The comment remains, but the replay shows as no longer available.

================================================================================
# Share session replays
URL: https://amplitude.com/docs/session-replay/share-replays
Updated: 2026-10-05
================================================================================

# Share session replays

Share a replay's URL to give colleagues the context behind a bug, a conversion drop, or a user interaction. Use [replay comments](https://amplitude.com/docs/session-replay/comment-on-replays) when you want to discuss the recording in Amplitude and notify teammates.

## Plan availability

Share session replay timestamps is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Copy a replay URL

1. Open the replay in a [User Look-Up event stream](https://amplitude.com/docs/session-replay/find-replays#view-session-replay-from-user-look-up).
2. Select **Copy URL** in the replay view.
3. Share the copied link with your team.

You can also copy and share a replay's URL from the chart replay modal. For programmatic sharing or external tools, use the [direct replay URL reference](https://amplitude.com/docs/session-replay/replay-link-reference).

To share a moment within a recording, [add a timestamp to a replay comment](https://amplitude.com/docs/session-replay/comment-on-replays#add-a-comment).

## Add a replay to a dashboard or notebook

You can add a replay to a dashboard or notebook from three places:

- The Session Replay page, accessible from your homepage or Session Replay search
- [User Look-Up](https://amplitude.com/docs/analytics/user-data-lookup)
- An individual chart

================================================================================
# Bookmark session replays
URL: https://amplitude.com/docs/session-replay/bookmarkable-session-replays
Updated: 2026-10-09
================================================================================

# Bookmark session replays

Bookmarking a session replay pins it so that Amplitude doesn't auto-delete the replay when your retention period expires. You can access all your bookmarked replays from the Bookmarks section of the Session Replay page. Use bookmarks to revisit sessions you've flagged for investigation, collaboration, or reference.

Amplitude normally auto-deletes replays after the applicable [retention period](https://amplitude.com/docs/session-replay/replay-data-lifecycle#retention-period). When you bookmark a replay, Amplitude exempts it from that policy. The replay stays available until you remove the bookmark.

Use bookmarks to help you:

- **Bug preservation**: Bookmark a replay that shows a critical bug before your retention period expires. The replay stays available for incident investigation or engineering reference.
- **UX review**: Save sessions that illustrate a confusing or broken user flow so you can return to the sessions during design reviews without searching your replay list.
- **Customer support**: Pin a replay tied to an open support case so you can reference the exact user experience while the case is active.

Bookmarks are specific to each user. Your bookmarks aren't visible to other team members.

## Bookmark a replay

1. Open the session replay you want to bookmark.
2. In the player toolbar, select the bookmark icon. The icon fills in to confirm the bookmark.
3. Amplitude saves the replay to your Bookmarks list.
4. In the main Session Replay section, click the **Bookmarks** tab to view all of your saved replays.

To remove a bookmark, select the filled bookmark icon again. The icon returns to its unfilled state and Amplitude removes the replay from your Bookmarks list.

> **Note:**
>
> You can also bookmark Replay Insights directly from the Insights view.

================================================================================
# Configure Session Replay sampling
URL: https://amplitude.com/docs/session-replay/configure-sampling
Updated: 2026-10-13
================================================================================

# Configure Session Replay sampling

Configure sampling to control how many sessions Amplitude captures within your organization's quota. Use a manual rate for a fixed capture percentage or dynamic sampling to adjust the rate each day. For capture based on events, properties, or URLs, use [Targeted Replay Capture](https://amplitude.com/docs/session-replay/targeted-replay-capture).

## Open project sampling settings

1. Go to _Settings > Organizational Settings > Session Replay Settings_.
2. Select the project you want to configure.
3. In _Sampling_, set a manual sample rate for the conditions you define, or choose dynamic sampling for the project.

## Sampling

View and set the sampling rate for any condition you define. The Sampling section shows a monthly estimate of sessions that match the conditions you define, and estimates how many sessions Amplitude captures. By default, Session Replay uses the Any Session condition. For more information about conditions, refer to [Targeted Replay Capture](https://amplitude.com/docs/session-replay/targeted-replay-capture).

### Choose a manual rate for your quota

Distribute your capture quota over the month. For example, a quota of 2,500,000 sessions divided by an average of 3,000,000 monthly sessions is about 83%. Set the SDK's `sampleRate` to `.83` or lower to spread capture through the month. For SDK parameter units and defaults, refer to your [Session Replay SDK](https://amplitude.com/docs/session-replay/instrument-session-replay).

Amplitude recommends starting with a low rate, such as `.01`. If that rate doesn't capture enough replays, increase it over a few days. Use [Measure replay capture](https://amplitude.com/docs/session-replay/measure-replay-capture) to monitor captures.

### Quota reset and capture limits

- Amplitude stops capturing replays when you reach the monthly session quota.
- Session quotas reset on the first of every month.
- Replays with [processing errors](https://amplitude.com/docs/session-replay/troubleshooting) don't count toward the monthly quota.
- Replays with a retention error already counted toward quota when the session was within the retention period.

## Dynamic sampling

If you're unsure how to balance your sample rate against your monthly quota, dynamic sampling may help. Dynamic sampling adjusts the sample rate each day so you use your full quota by month end. Dynamic sampling helps you stay within your quotas, but Amplitude can't guarantee an exact 100% match or prevent overage. Choose which projects use dynamic sampling. Session Replay quota is org-wide, but the sampling rate is per project. If you enable dynamic sampling on multiple projects, those projects share the same sample rate.

### How dynamic sampling sets the rate

Each day, Amplitude estimates your org's projected replay count by month end using analytics session counts across all projects with session capture enabled. For projects with a manual sample rate, Amplitude multiplies that rate by the project's session count to estimate each project's quota consumption. It then allocates the remaining quota to dynamic-sampling projects and sets their rates accordingly.

Because the estimate relies on analytics session counts rather than actual replay captures, discrepancies between the two can affect the result. For example, a project with a large analytics session count and a 100% manual sample rate may appear to consume most or all of the monthly quota, even if it isn't actively capturing replays. In this case, dynamic-sampling projects may receive a 0% rate early in the month.

To improve the accuracy of dynamic sampling:

- Configure the sample rate in Session Replay settings for every project with session capture enabled.
- For projects that aren't capturing replays, set the sample rate to 0% or disable session capture so their session counts don't inflate the org-wide estimate.
- Dynamic sampling works best when all projects in your org use it. You can mix dynamic and manual rates, but the estimate is less accurate when analytics session counts don't match actual replay captures.

A project can't have both [targeted session replay capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) and dynamic sampling on.

================================================================================
# Capture targeted sessions
URL: https://amplitude.com/docs/session-replay/targeted-replay-capture
Updated: 2026-10-29
================================================================================

# Capture targeted sessions

Targeted Replay Capture (TRC) focuses your Session Replay quota on sessions that match criteria you define, such as events, event properties, user properties, or page URLs, rather than capturing all sessions or relying on random sampling. Use TRC when you need to observe specific behaviors or high-value segments; if you only need broad session coverage, [configure a global sample rate](https://amplitude.com/docs/session-replay/configure-sampling) instead.

Configure TRC by adding conditions to the _Sampling_ control in your project's Session Replay settings. Each condition can match events, event properties, user properties, or page URLs, and you can combine conditions with OR logic. The Session Replay SDK fetches targeting configurations from a remote config service and evaluates them at runtime to decide whether to capture a session.

## Plan availability

Targeted Replay Capture is available as an add-on on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details.

| Plan | Allowance | How to access |
| --- | --- | --- |
| Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) |
| Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) |
| Growth | Not included | Available as an add-on. |
| Enterprise | Not included | Available as an add-on. |

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Key capabilities

TRC defines the criteria that Amplitude uses to decide whether to capture a session, and helps you manage your Session Replay quota more efficiently.

### Custom capture criteria

Define rules that capture replays based on:

- **Specific events**: For example, `Checkout Started`.
- **Event properties**: For example, `plan = Pro`.
- **User properties**: For example, `country = US`.
- **Page URLs**: For example, capture only sessions on `/checkout` or any URL matching a pattern.
- **Combinations**: Combine these criteria with `OR` logic.

### Configuration and quota management

Manage TRC through the [Session Replay settings page](https://amplitude.com/docs/session-replay/session-replay-settings) by adding conditions to the _Sampling_ control. Add, edit, and remove targeting conditions for each project. The UI estimates how much quota each condition uses based on historical traffic. Set different sample rates for different conditions to control which sessions Amplitude captures and how much quota each condition uses.

## Use cases

- Capture replays only for users who encounter errors or drop off at key points.
- Focus on high-value user segments or critical product flows.
- Capture sessions on specific pages or flows, such as checkout or onboarding.
- Reduce noise and cost by avoiding unnecessary replay capture.

## Configure Targeted Replay Capture

You need [permissions to manage Session Replay settings](https://amplitude.com/docs/admin/account-management/user-roles-permissions) and an SDK that supports your condition type. Check the [SDK support matrix](#sdk-support) before configuring conditions.

> **Warning:**
>
> TRC conditions don't take effect until you set a default sample rate in the Session Replay settings UI. Until you set a default sample rate, Session Replay uses the sample rate and settings configured in the SDK.

Configure TRC per project:

1. Navigate to _Settings > Organizational Settings > Session Replay Settings_. For more information, refer to the [Session Replay settings page](https://amplitude.com/docs/session-replay/session-replay-settings).
2. Select the project you want to configure.
3. In the _Sampling_ section, select **Add Condition** to create a new targeting condition.
4. Define your targeting criteria for the condition.

Add multiple conditions and combine them with OR logic. Each condition can include:

- Event types.
- Event properties.
- User properties.
- Page URLs (web only).

> **Note:**
>
> You must capture and send events, event properties, and user properties to Amplitude during the session for event- and property-based targeting conditions to work. Page URL conditions evaluate the user's current URL directly and don't require a matching event.

## Page URL targeting

Page URL targeting captures replays only when users visit specific pages or URL patterns. This capability is in beta for web Session Replay.

Check [SDK support](#sdk-support) for the minimum plugin and standalone versions.

To add a Page URL condition:

1. In the _Sampling_ section, select **Add Condition** and open the condition editor.
2. Add a **Page URL** condition.
3. Select an operator and enter a URL or pattern.
4. Set the sample rate for the condition and save.

Supported operators:

| Operator | Matches when |
| --- | --- |
| is | The current page URL exactly matches the value you enter. |
| is not | The current page URL doesn't exactly match the value you enter. |
| contains | The current page URL includes the text you enter. |
| does not contain | The current page URL doesn't include the text you enter. |
| glob match | The current page URL matches a glob pattern. For example, `https://example.com/checkout/*` matches any checkout subpath. |

> **Tip:**
>
> Use Page URL targeting to focus replay capture on high-value flows such as checkout, onboarding, or account settings without capturing every session.

### How Page URL targeting evaluates

For URL evaluation and capture start behavior, go to [Evaluation timing](#evaluation-timing).

## SDK support

TRC works with the web and iOS Session Replay SDKs. Android support is coming soon.

### Web

| Condition type | Browser plugin | Browser standalone SDK |
| --- | --- | --- |
| Events, event properties, and user properties | `@amplitude/plugin-session-replay-browser@1.22.0` or higher, with the Amplitude Browser Analytics SDK | Unsupported |
| Page URLs | `@amplitude/plugin-session-replay-browser@1.26.2` or higher | `@amplitude/session-replay-browser@1.32.2` or higher |

Event- and property-based targeting requires the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) with the Amplitude Browser Analytics SDK. The standalone SDK supports Page URL targeting only.

### iOS

| Condition type | iOS plugin | iOS standalone SDK |
| --- | --- | --- |
| Events, event properties, and user properties | `AmplitudeSessionReplay` 0.15.0 or higher, with the iOS Swift SDK | `AmplitudeSessionReplay` 0.15.0 or higher; your app passes events and user properties |
| Page URLs | Not applicable | Not applicable |

The [Session Replay iOS Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin) evaluates conditions against each event and the user's properties without extra code. With the [standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#targeted-replay-capture), your app passes each event and the user's properties to Session Replay.

The [Segment plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration), the [Session Replay iOS Middleware](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-middleware), Flutter, and React Native don't evaluate TRC conditions yet. When your project has targeting conditions, Session Replay captures sessions from these integrations at your project's sample rate only.

## Evaluation timing

On web, the SDK fetches targeting configuration at session start. Event-, property-, and user-based conditions use that configuration throughout the session, including when a matching event occurs later. Updates to targeting rules apply only to new sessions.

The SDK evaluates Page URL conditions against the current browser URL and re-evaluates when the URL changes, including single-page app navigation. After a session meets targeting conditions, capture continues for the remainder of the session.

On iOS, the SDK fetches targeting configuration when it initializes and when a new session starts. It evaluates conditions when the configuration arrives, when a session starts, on each event, and when the user's properties change. A configuration update applies to sessions that haven't started capturing, so changes usually take effect from the next session. With the iOS plugin, user property conditions use the properties your app sets with `identify` during the current app launch. After the app restarts, Session Replay uses them again once your app identifies the user.

> **Note:** Capture timing
>
> Capture starts when the targeting condition triggers. For event-based conditions, capture starts when the matching event fires. For Page URL conditions, capture starts when the URL matches. TRC has no lookback period: replays don't include activity before the condition triggers.

================================================================================
# Manage privacy settings for Session Replay
URL: https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay
Updated: 2026-10-06
================================================================================

# Manage privacy settings for Session Replay

Web Session Replay privacy settings control which user data appears in a replay and which data Amplitude masks. Configure masking, blocking, and PII handling to meet your organization's legal and security requirements. After you configure these settings, Session Replay applies them consistently across every session. Use masking for page text and form inputs; [filter sensitive URL content](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules) for URLs.

When these privacy settings are active, Amplitude masks the user data you specify in all session replays you create and view. Masking data prevents Amplitude from receiving it from your product. Masking doesn't remove the data from your own product data repository.

## Plan availability

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

_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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Masking levels

Session Replay provides three presets for masking sensitive data in your screen recordings. The descriptions below apply to browser capture. For mobile masking, follow the [iOS](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk#configuration), [Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone#configuration), [React Native](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk#mask-onscreen-data), or [Flutter](https://amplitude.com/docs/sdks/session-replay/session-replay-flutter-standalone-sdk#mask-onscreen-data) guide. You can also implement custom overrides when necessary.

- **Medium**: This is the default option for Session Replay privacy settings. When selected, Medium masks all form fields and text inputs. Amplitude captures all other text as-is.
- **Light**: This option is for companies that retain very little sensitive customer data, and for those who want to start quickly and selectively choose which fields to mask. Selecting this option masks only a subset of sensitive inputs, such as passwords, credit card numbers, telephone numbers, and email addresses. Examples of companies that might choose this option are business productivity app developers, restaurant- or appointment-booking software companies, and ecommerce sites.
- **Conservative**: This option is for companies that retain a large amount of sensitive customer data. Selecting this option masks all text and all form fields, including HTML text, user input, and links. Conservative masking doesn't apply to text in pictures, videos, thumbnails, or other static assets. [Use CSS Selectors](https://www.w3schools.com/cssref/css_selectors.php) to exclude any pictures, videos, or thumbnails that contain sensitive information. Examples of companies that might choose this option are financial services firms, CRM systems, online betting companies, geospatial technology companies, and companies in the healthcare and medical technology industries. In these sectors, the inadvertent release of sensitive user data could have serious repercussions.

Project privacy levels override SDK levels when remote configuration is enabled. Before production rollout, [verify masking in a test replay](https://amplitude.com/docs/session-replay/verify-capture#capture-a-test-session).

> **Warning:** Browser HTML attribute masking limitation
>
> Session Replay masking applies to text content and form inputs, but doesn't mask HTML attribute values. Attributes such as `alt`, `title`, `placeholder`, `aria-label`, `value`, and custom `data-*` attributes remain visible in replays even when you enable masking. If your application stores sensitive information in HTML attributes, remove or obfuscate that data before it reaches Session Replay.

## Set your privacy level

To set the Session Replay privacy level, navigate to _Settings > Organizational Settings > Session Replay Settings_ and select the appropriate project. Each project has its own settings. You can always view a summary of your masking level and overrides for each project on the main Session Replay Settings page.

### Override preset policy levels

You can override the default masking settings for individual elements by editing the matching [CSS selectors](https://www.w3schools.com/cssref/css_selectors.php) of those elements.

To override masking settings, right-click on your application and select Inspect mode. Under _Masking Overrides_, enter the CSS selector you want to change and select **+ Add Selector**. You can use this process to mask, unmask, or exclude individual elements.

Unmasking an element also unmasks its child elements. If needed, you can re-mask these child elements using the process above. However, when you mask an element using CSS selectors, Amplitude also masks its child elements. You can't then unmask these child elements.

When you exclude an element using CSS selectors, Amplitude replaces the element with an empty placeholder element of the same dimensions. Amplitude also excludes any child elements.

#### mask

![Diagram showing that masking a parent element masks its child elements, which you can't unmask](https://amplitude.com/docs/images/session-replay/image2.png)

#### unmask

![Diagram showing that you can mask or exclude child elements after unmasking a parent element](https://amplitude.com/docs/images/session-replay/image1.png)

#### exclude

![Diagram showing that excluding a parent element excludes its child elements, which you can't mask or unmask](https://amplitude.com/docs/images/session-replay/image3.png)

> **Tip:** Avoid site performance issues with masking
>
> If you experience a decrease in site performance due to the number of [masking](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#mask-on-screen-data) rules you create, Amplitude recommends excluding or blocking content with the `.amp-block` class, rather than masking it.
>
> Blocking or excluding content replaces the element with a placeholder of the same dimensions.

## How Session Replay resolves conflicts between the SDK and the UI

When the SDK and the Session Replay settings page conflict on how to handle a particular element (whether Amplitude should mask, unmask, or exclude it), the Session Replay settings page takes precedence.

For example, imagine you have used the Session Replay settings page to mask `.selector1` and unmask `.selector2`. An engineer then changes the SDK to mask `.selector3`, and at the same time inadvertently unmasks `.selector1`.

In this case, Session Replay combines the settings from the SDK and the UI, but the settings specified for `.selector1` in the UI take precedence:

|  | `.selector1` | `.selector2` | `.selector3` |
| --- | --- | --- | --- |
| Session Replay settings | MASK | UNMASK |  |
| SDK settings | UNMASK |  | MASK |
| End results | MASK | UNMASK | MASK |

> **Note:** Remote configuration
>
> If you enable remote configuration and it fails to load, Session Replay doesn't capture any sessions. This behavior ensures that Amplitude respects any privacy settings you define in the Admin interface, and that you don't accidentally capture sensitive data.

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

================================================================================
# Manage user consent for Session Replay
URL: https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent
Updated: 2026-10-05
================================================================================

# Manage user consent for Session Replay

When you use Session Replay, you must disclose the recording in your privacy policy and capture user consent where local privacy laws require it. These best practices cover how to word your privacy policy disclosure, set up cookie banners and consent management tools, and apply Amplitude's built-in privacy controls.

## Disclosure and consent

Session Replay reconstructs and analyzes real user interactions on your site or app. Some jurisdictions require a notice or consent for this kind of tracking.

## Inclusions for your privacy policy

Amplitude recommends that you update your privacy policy to clearly explain:

- That you use Session Replay technology.
- The kind of data you collect, such as clicks, navigation patterns, or form interactions.
- The reason you collect this data, such as to improve usability, troubleshoot issues, or better understand user behavior.
- The categories of third parties with which you share personal information.
- How you store, process, and protect data.
- The options that users have to opt out, if applicable.

Privacy laws vary across states and countries. Review your privacy notice when you implement Session Replay to ensure the disclosures remain accurate and complete. Review the notice with legal counsel to ensure it meets the privacy laws and requirements that apply to your business and personal information practices.

### Sample disclosure language

Modify the following examples to match your company's tone and policy structure.

> We may use cookies and similar technologies to collect information about our customers' interactions with our products and services in a manner that allows us to reproduce and fix issues and to identify areas of improvement for our products and services. You can opt out of the use of this software by contacting us at privacy@company.com.

> We use session replay technology to help us understand how users interact with our website and improve their experience. This technology captures user interactions, such as clicks, scrolling, and typing behavior, so we can identify usability issues and optimize our content. Sensitive information is automatically masked, and we do not use Session Replay to collect or store passwords, credit card numbers, or other sensitive data.

## Cookie banners or consent management tools

In regions that require prior consent, like the EU, include Session Replay in your cookie consent banner or Consent Management Platform (CMP). Amplitude's Session Replay SDK integrates Session Replay and its associated cookies with your CMP.

### Cookie and consent banner tips

Apply the following best practices when you update your banners:

- Categorize Session Replay under "analytics" or "functional" cookies. Session Replay cookies are first-party cookies, and Amplitude never uses your data for its own purposes.
- Don't enable Session Replay by default before consent, if your local laws require consent.
- Give users clear control over enabling or disabling Session Replay.
- Consider including a link to your privacy policy or a dedicated Session Replay information page.

### Sample banner wording

Modify the following examples to match your company's tone and style.

> We use cookies on our websites. Your interactions with our website and associated personal data may be collected by us in accordance with our Privacy Policy \[hyperlink to privacy policy that includes session replay disclosure\].

> We use cookies to personalize content and analyze traffic. We also use tools like session replay to better understand how users navigate our site and improve their experience. You can choose which cookies to allow.

## Amplitude's privacy controls

To help you stay compliant, Session Replay includes:

- [Privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) to fit your privacy requirements.
- Custom masking options that let you define which elements Session Replay captures or excludes.
- [Configurable data retention](https://amplitude.com/docs/session-replay/replay-data-lifecycle) to meet your company's data lifecycle policies.

For more information about Amplitude's privacy approach, refer to [Building a privacy-first Session Replay](https://amplitude.com/blog/session-replay-privacy) and [Amplitude Trust](https://amplitude.com/trust). For legal guidance, consult your legal team or privacy counsel.

================================================================================
# Filter sensitive URL content
URL: https://amplitude.com/docs/session-replay/configure-ugc-filter-rules
Updated: 2026-11-04
================================================================================

# Filter sensitive URL content

Configure `ugcFilterRules` to replace sensitive user-generated content in URLs before the SDK records URLs in replays and heatmaps. Use [web masking settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) to protect page text and form inputs.

1. Identify URLs that contain sensitive user IDs, company names, query parameters, or dynamic path segments.
2. Choose selectors and descriptive replacement URLs using the [UGC Filter Rules reference](https://amplitude.com/docs/session-replay/ugc-filter-rules).
3. Put specific rules before general rules. The SDK uses the first matching rule.
4. Add the rules to `interactionConfig` during SDK initialization and set `enabled: true`.

## Configure UGC Filter Rules

Configure UGC Filter Rules as part of the `interactionConfig` when initializing Session Replay. The Standalone SDK, the [Browser SDK plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin), and the `sessionReplay` options of the [Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started) all accept the same `interactionConfig` object.

#### Plugin

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

amplitude.add(
  sessionReplayPlugin({
    interactionConfig: {
      enabled: true,
      ugcFilterRules: [
        {
          selector: "https://example.com/user/*/profile",
          replacement: "https://example.com/user/USER_ID/profile",
        },
      ],
    },
  }),
);
amplitude.init("AMPLITUDE_API_KEY");
```

#### Unified SDK

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

initAll("AMPLITUDE_API_KEY", {
  sessionReplay: {
    interactionConfig: {
      enabled: true,
      ugcFilterRules: [
        {
          selector: "https://example.com/user/*/profile",
          replacement: "https://example.com/user/USER_ID/profile",
        },
      ],
    },
  },
});
```

#### Standalone SDK

```javascript
import { sessionReplay } from "@amplitude/session-replay-browser";

sessionReplay.init("AMPLITUDE_API_KEY", {
  // ...
  // Other Configs
  // ...
  interactionConfig: {
    enabled: true,
    ugcFilterRules: [
      {
        selector: "https://example.com/user/*/profile",
        replacement: "https://example.com/user/USER_ID/profile",
      },
      {
        selector: "https://example.com/api/token=*",
        replacement: "https://example.com/api/token=REDACTED",
      },
    ],
  },
});
```

## Test patterns in a development environment first

Validate that your glob patterns match expected URLs in a development environment. The following array lists example URLs to include in your checks; it doesn't execute a test:

```javascript
// Test with various URL formats
const testUrls = [
  "https://mycompany.projecttool.com/browse/PROJ-123",
  "https://codehost.com/username/repository/tree/main/src/components",
  "https://myapp.com/user/john.doe@email.com/profile",
];
```

================================================================================
# Self-host the browser Session Replay script
URL: https://amplitude.com/docs/session-replay/self-host-browser-script
Updated: 2026-10-05
================================================================================

# Self-host the browser Session Replay script

Serve the Session Replay SDK script from your own domain when your browser installation loads the SDK through a `<script>` tag. An npm installation bundled with your app doesn't need this step. Script hosting and [proxying replay requests](https://amplitude.com/docs/session-replay/proxy-replay-requests) are independent tasks.

## Self-host the SDK script

Self-hosting the SDK script applies to browser-based SDKs loaded through a `<script>` tag. If you install through npm and bundle the SDK yourself, skip to [Proxy replay requests](https://amplitude.com/docs/session-replay/proxy-replay-requests).

### Get the SDK file

Option A: Download from Amplitude's CDN:

```bash
# Session Replay Plugin (example version: 1.28.1)
curl -O https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz

# Session Replay Standalone SDK (example version: 1.39.0)
curl -O https://cdn.amplitude.com/libs/session-replay-browser-1.39.0-min.js.gz

# Browser SDK (example version: 2.42.0 — only needed if also self-hosting analytics)
curl -O https://cdn.amplitude.com/libs/analytics-browser-2.42.0-min.js.gz
```

Option B: Pull from npm:

```bash
pnpm pack @amplitude/plugin-session-replay-browser@1.28.1
# or
pnpm pack @amplitude/session-replay-browser@1.39.0
```

The `pnpm pack` command produces a `.tgz` tarball. Extract the tarball and locate the UMD bundle inside the `package/lib/scripts/` directory, for example, `plugin-session-replay-browser-1.28.1.umd.js`. Serve that file from your own origin.

These examples pin SDK versions. To choose another version, refer to [the plugin package](https://www.npmjs.com/package/@amplitude/plugin-session-replay-browser) or [the standalone package](https://www.npmjs.com/package/@amplitude/session-replay-browser) on npm.

### Serve the file

Host the file on your own CDN or static file server, then update your `<script>` tags:

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

<!-- After -->
<script src="https://assets.yourdomain.com/libs/analytics-browser-2.42.0-min.js.gz"></script>
<script src="https://assets.yourdomain.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz"></script>
```

> **Tip:** Cache TTL
>
> If you plan to update the SDK version frequently, set a short cache TTL (1 to 5 minutes) on your file server. If you pin to a specific version and update manually, a longer TTL is fine.

## Content Security Policy

If your app sets a Content Security Policy, replace `https://cdn.amplitude.com` in `script-src` with your file-serving domain. Keep `blob:` in `worker-src`, because the Session Replay web worker requires it. If you also proxy network requests, follow the [proxy CSP configuration](https://amplitude.com/docs/session-replay/proxy-replay-requests#content-security-policy-csp).

================================================================================
# Proxy Session Replay requests
URL: https://amplitude.com/docs/session-replay/proxy-replay-requests
Updated: 2026-11-04
================================================================================

# Proxy Session Replay requests

Proxy Session Replay requests when you need SDK network traffic to pass through your own domain before reaching Amplitude. In the browser, you can proxy requests independently of [hosting the browser script](https://amplitude.com/docs/session-replay/self-host-browser-script). The iOS and Android SDKs support a custom URL for replay uploads.

## Proxy API calls

Route SDK network requests through your own server so they don't go directly to `amplitude.com` endpoints. Your proxy server receives the request, forwards it to Amplitude's default endpoint, and returns Amplitude's response unchanged.

### How the proxy works

A minimal proxy implementation should:

1. Accept requests from the SDK at your custom URL.
2. Forward the full request body and all headers (except `Host`) to the corresponding Amplitude endpoint.
3. Return Amplitude's response to the SDK unchanged, including the status code, headers, and body.

Your proxy should be transparent. Don't strip, modify, or buffer the request or response payload. The SDK handles retries, so your proxy doesn't need to.

> **Tip:** Keep your API key server-side
>
> If you need to inject an `Authorization` header for a downstream service, inject the header in your proxy rather than hardcoding the API key in client-side code. Injecting the header server-side keeps credentials out of the browser.

### Optional Analytics SDK proxy

Analytics SDKs use separate ingestion and remote configuration endpoints. If your implementation also captures Analytics events, go to [Proxy Analytics SDK requests](https://amplitude.com/docs/sdks/analytics/proxy-requests).

### Session Replay: Browser (Plugin and Standalone SDK)

Session Replay sends captured data and fetches remote configuration through separate endpoints. Forward each request to the corresponding [API endpoint for your region](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#api-endpoints).

| Config option | Purpose |
| --- | --- |
| `trackServerUrl` | Point replay uploads to your proxy. |
| `configServerUrl` | Point remote configuration requests to your proxy. |

Session Replay Plugin:

```js
sessionReplayPlugin({
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});
```

Session Replay Standalone SDK:

```js
sessionReplay.init('AMPLITUDE_API_KEY', {
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});
```

### Session Replay: Mobile (iOS and Android)

The iOS and Android SDKs send replay uploads to your proxy when you set a custom server URL. Point the SDK at the full upload URL on your proxy, and have the proxy forward each request to `https://api-sr.amplitude.com/sessions/v2/track` (US) or `https://api-sr.eu.amplitude.com/sessions/v2/track` (EU) with the query string, headers, and body unchanged. A custom server URL overrides `serverZone`.

| SDK | Config option | Minimum version |
| --- | --- | --- |
| iOS plugin, standalone SDK, middleware, and Segment plugin | `UploadConfig(serverUrl:)` | 0.14.0 |
| Android plugin, standalone SDK, and Segment plugin | `serverUrl` | All supported versions |
| Android middleware | `SessionReplayMiddleware.Builder.serverUrl()` | 0.33.0 |

The mobile SDKs fetch remote configuration directly from Amplitude. They don't support a custom remote configuration URL yet.

iOS plugin:

```swift
let config = AmplitudeSwiftSessionReplayPlugin.Config(
    sampleRate: 1.0,
    uploadConfig: UploadConfig(serverUrl: "https://replay.yourdomain.com/sessions/v2/track")
)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(config: config))
```

Android plugin:

```kotlin
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    sampleRate = 1.0,
    serverUrl = "https://replay.yourdomain.com/sessions/v2/track"
)
amplitude.add(sessionReplayPlugin)
```

Android middleware:

```kotlin
val sessionReplayMiddleware = SessionReplayMiddleware.Builder(amplitude)
    .sampleRate(1.0)
    .serverUrl("https://replay.yourdomain.com/sessions/v2/track")
    .build()
amplitude.addEventMiddleware(sessionReplayMiddleware)
```

The React Native and Flutter Session Replay SDKs don't support custom proxy URLs. Their `serverZone` option selects Amplitude's US or EU data center, and requests go directly to Amplitude.

## Content Security Policy (CSP)

If your app sets a Content Security Policy, update it when switching to self-hosted files and proxied endpoints.

| Directive | Default (Amplitude CDN) | With self-hosting |
| --- | --- | --- |
| `script-src` | `https://cdn.amplitude.com` | Your own file-serving domain |
| `connect-src` | `https://api-sr.amplitude.com` (US) or `https://api-sr.eu.amplitude.com` (EU) | Your proxy domain(s) |
| `worker-src` | `blob:` | Keep `blob:`, required by the Session Replay web worker |

Example CSP (fully self-hosted):

```text
Content-Security-Policy: script-src 'self' https://assets.yourdomain.com; connect-src 'self' https://analytics.yourdomain.com https://replay.yourdomain.com; worker-src 'self' blob:;
```

Because your proxy handles routing to Amplitude's US or EU endpoints, the CSP only needs to reference your own domain. The same policy works for both regions.

================================================================================
# Add Session Replay alongside another analytics tool
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk
Updated: 2026-11-04
================================================================================

# Add Session Replay alongside another analytics tool

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

Use the Session Replay standalone SDK (`@amplitude/session-replay-browser`) to record user sessions on a site that sends analytics to a provider other than Amplitude. The SDK runs independently of the Amplitude Browser SDK. You pass it the device ID and session ID from your existing analytics tool so Amplitude can match each replay to your events.

If your site already uses the Amplitude Browser SDK, use the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) instead. For a new installation, start with [Install Session Replay](https://amplitude.com/docs/session-replay/instrument-session-replay) to choose between the Unified SDK, a plugin, and a standalone SDK.

## 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](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._

## Prerequisites

Session Replay Standalone SDK requires that:

1. Your application is web-based.
2. You provide a session identifier to the SDK at initialization and call `setSessionId` when it changes. The SDK uses this ID to bucket replay data. For session ID matching, use the same session identifier on analytics events and in the SDK. With [time-based event matching](https://amplitude.com/docs/session-replay/session-matching#time-based-event-matching) only, the Session Replay `sessionId` can be a frontend-generated time bucket (for example, an hour-aligned Unix timestamp in milliseconds) that doesn't appear on analytics events.
3. You can provide a device ID to the SDK.
4. The `Device ID` you pass to the Standalone SDK must match the device ID on your analytics events.

The Standalone SDK doesn't provide session management capabilities. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

## Quickstart

Install the SDK with npm or yarn.

> **Info:** Unified SDK
>
> Install the [Browser Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/get-started) to access the Experiment SDK along with other Amplitude products (Analytics, Session Replay). The Unified SDK provides a single entry point for all Amplitude features and handles the initialization and configuration of all components.

#### npm

```bash
# Install Session Replay SDK only
npm install @amplitude/session-replay-browser --save

# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified
```

#### yarn

```bash
# Install Session Replay SDK only
yarn add @amplitude/session-replay-browser

# Or install Unified SDK to get access to all Amplitude products
yarn add @amplitude/unified
```

Configure your application code.

1. Call `sessionReplay.init` to begin collecting replays. Pass the API key, session identifier, and device identifier.
2. When the session identifier changes, pass the new value to Amplitude with `sessionReplay.setSessionId`.
3. Amplitude automatically creates the `[Amplitude] Replay Captured` event to link replays with your analytics data. Refer to [Session Replay ID](#session-replay-id) for more information.

Set `sampleRate` explicitly. The default is `0`, which records no sessions. The following examples use `1` to record every session while you test. Lower it before production, or [set the sample rate remotely](https://amplitude.com/docs/session-replay/configure-sampling).

#### Standalone SDK

```js
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'

const API_KEY = 'AMPLITUDE_API_KEY'

// Configure the SDK and begin collecting replays
await sessionReplay.init(API_KEY, {
  deviceId: "<string>",
  sessionId: "<string | number>",
  optOut: false,
  sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
}).promise;

// Call whenever the session id changes
await sessionReplay.setSessionId(sessionId).promise;
```

#### Unified SDK

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

// Initialize the Unified SDK with your API key
// The Unified SDK automatically handles:
// - Device ID and Session ID management
// - Session ID changes
// - Event property collection and tracking
initAll("AMPLITUDE_API_KEY", {
  sessionReplay: {
    sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
  },
});

// Call session replay APIs
sessionReplay.shutdown();
```

> **Info:**
>
> Session Replay instrumentation happens in the context of an Amplitude project. Amplitude defines your replay quota at the organization level. You may have multiple Session Replay implementations across multiple projects, each with its own sample rate, that pull from the same quota.

You can also use script tags to instrument Session Replay:

```js
<script src="https://cdn.amplitude.com/libs/session-replay-browser-1.51.7-min.js.gz"></script>
<script>
window.sessionReplay.init("AMPLITUDE_API_KEY", {
    deviceId: "<string>",
    sessionId: "<string | number>",
    sampleRate: 1, // Records 100% of sessions for initial testing. Lower this for production; the SDK default (0) records nothing.
    //...other options
})

// Call whenever the session id changes
window.sessionReplay.setSessionId(sessionId);
</script>
```

## Session Replay ID

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. This event includes the `[Amplitude] Session Replay ID` property, which links the replay to your analytics data. Manual instrumentation isn't required.

`[Amplitude] Session Replay ID` is a unique identifier for the replay, and differs from `[Amplitude] Session ID`, which identifies the user's session by default.

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, `deviceId` and custom session ID string values can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

> **Info:**
>
> Amplitude links replays with a session replay ID. To combine multiple sessions into a single replay, ensure each session references the same device ID and session ID.

> **Note:** Legacy implementations
>
> If you have a legacy implementation that manually adds the `[Amplitude] Session Replay ID` property to events using `getSessionReplayProperties()`, this continues to work. However, Amplitude recommends the automatic `[Amplitude] Replay Captured` event.

> **Warning:** Not seeing replays?
>
> If replays don't appear in the Amplitude UI, check that the `[Amplitude] Replay Captured` event appears in your project. If you don't see this event, contact Amplitude support.

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `deviceId` | `string` | Yes | `undefined` | Sets an identifier for the device running your application. |
| `sessionId` | `string | number` | Yes | `undefined` | Sets an identifier for the user's current session. Use a Unix timestamp in milliseconds (`number`) for standard session tracking, or a custom string for [custom session definitions](https://amplitude.com/docs/session-replay/session-matching#requirements-for-custom-session-definitions). Custom string values must follow the [accepted character set](#session-replay-id). |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Amplitude selects 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. Sample rates as small as six decimal places (`0.000001`) work. |
| `optOut` | `boolean` | No | `false` | Sets permission to collect replays for sessions. A value of true prevents Amplitude from collecting session replays. |
| `flushMaxRetries` | `number` | No | `5` | Sets the maximum number of retries for failed upload attempts. This applies only to errors that Amplitude can retry. |
| `logLevel` | `number` | No | `LogLevel.Warn` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. Sets the log level. |
| `loggerProvider` | `Logger` | No | `Logger` | Sets a custom `loggerProvider` class from the Logger to emit log messages to your destination. |
| `serverZone` | `string` | No | `US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. |
| `privacyConfig` | `object` | No | `undefined` | Supports advanced masking configurations with CSS selectors. Refer to [Mask on-screen data](#mask-on-screen-data) for more information. |
| `applyBackgroundColorToBlockedElements` | `boolean` | No | `false` | If true, applies a background color to blocked elements for visual masking. This helps visualize which elements Amplitude blocks from capture in the replay. |
| `debugMode` | `boolean` | No | `false` | Adds the `[Amplitude] Session Replay Debug` event property, which contains a hash of your API key, to help debug instrumentation issues such as mismatched apps. Amplitude recommends this only for debugging initial setup, not for production. |
| `configServerUrl` | `string` | No | `undefined` | Specifies the endpoint URL to fetch remote configuration. If provided, it overrides the default server zone configuration. |
| `trackServerUrl` | `string` | No | `undefined` | Specifies the endpoint URL to send session replay data. If provided, the SDK forwards requests there instead of to the default SR endpoint. |
| `shouldInlineStylesheet` | `boolean` | No | `true` | If Amplitude inlines stylesheets, it stores the contents of the stylesheet. During replay, Amplitude 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 this is undefined, Amplitude inlines stylesheets. |
| `storeType` | `string` | No | `idb` | Specifies how Amplitude stores replay events. `idb` uses IndexedDB to persist replay events when the SDK 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, Amplitude 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 executing 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` |

### 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

Session Replay provides an opt-out configuration option. When passed as part of initialization, this prevents Amplitude from collecting session replays. For example:

```js
// Pass a boolean value to indicate a users opt-out status
await sessionReplay.init('AMPLITUDE_API_KEY', {
  optOut: true,
}).promise;
```

### 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",
}).promise;
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. 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 `sessionReplay.shutdown()`.

Call `sessionReplay.shutdown()` before a user navigates to a restricted area of your site to disable replay collection while the user is in that area.

Call `sessionReplay.init(API_KEY, {...options})` to re-enable replay collection when the user returns to an unrestricted area of your site.

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, you can create a feature flag that targets a specific user group, and add that to your initialization logic:

```js
import * as sessionReplay from "@amplitude/session-replay-browser";
import 3rdPartyAnalytics from 'example'

const API_KEY = 'AMPLITUDE_API_KEY'
await sessionReplay.init(API_KEY, {
 deviceId: <string>,
 sessionId: <string | number>,
 optOut: <boolean>,
 sampleRate: <number>
}).promise;
```

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

## Performance

> **Info:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on web page performance by:
>
> - Processing asynchronously through webhooks (if enabled) for efficient compression and optimized bundle sizes.
> - Using batching and lightweight compression to reduce network connections and bandwidth.
> - Optimizing DOM processing.

### Bundle size

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

For current bundle size information, check the [npm package page](https://www.npmjs.com/package/@amplitude/session-replay-browser) or [BundlePhobia](https://bundlephobia.com/package/@amplitude/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 takes 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. Amplitude defers compression operations to browser idle periods when `performanceConfig.enabled` is `true` (default).
- **Network bandwidth**: Amplitude compresses replay data before upload, typically reducing payload size by 60-80%. Amplitude batches network requests and sends them asynchronously.

### Performance optimization

To optimize Session Replay performance:

- Enable `useWebWorker` to move compression off the main thread, reducing CPU impact on the main thread.
- Configure `performanceConfig.timeout` to control when deferred compression occurs.
- Use `sampleRate` to reduce the number of sessions captured, which directly reduces CPU and memory usage.
- Set `storeType` to `memory` if you don't need persistence across page reloads, reducing IndexedDB overhead.

For detailed performance testing results, refer 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, then replays these changes to build a video-like replay. 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.

Use a `load` event listener to defer initialization:

```js
import 3rdPartyAnalytics from 'example';

window.addEventListener('load', async () => {
  const sessionReplay = await import('@amplitude/session-replay-browser');
  await sessionReplay.init('AMPLITUDE_API_KEY', {
    deviceId: '<string>',
    sessionId: '<string | number>',
    sampleRate: 0.5,
  }).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 3rdPartyAnalytics from 'example';

requestIdleCallback(async () => {
  const sessionReplay = await import('@amplitude/session-replay-browser');
  await sessionReplay.init('AMPLITUDE_API_KEY', {
    deviceId: '<string>',
    sessionId: '<string | number>',
    sampleRate: 0.5,
  }).promise;
});
```

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

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

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

### 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

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

#### 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).

================================================================================
# Cross-origin iframe recording
URL: https://amplitude.com/docs/sdks/session-replay/cross-origin-iframes
Updated: 2026-11-04
================================================================================

# Cross-origin iframe recording

The Session Replay Browser SDK can capture DOM changes inside cross-origin `<iframe>` elements and merge them into the parent page's replay stream. Both the parent page and each child iframe page must load the SDK with `crossOriginIframes.enabled: true`.

This article covers configuration, privacy behavior, limitations, and troubleshooting.

> **Note:** Browser SDK only
>
> Cross-origin iframe recording applies to the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin) and [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). Mobile Session Replay SDKs don't support this feature.

## How it works

When you enable cross-origin iframe recording on the parent page, the SDK:

1. Watches for `<iframe>` elements added to the DOM.
2. Sends `start` and `stop` signals to child frames over `postMessage`.
3. Relays child rrweb events into the parent replay stream so the replay viewer can reconstruct both frames from a single session.

The child SDK detects when it runs inside an iframe and waits for a start signal from the parent before it begins recording.

## Setup

Load the Session Replay SDK on both the parent page and each child iframe page you want to capture.

### Parent page

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

sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});
```

If you use the Browser SDK plugin, pass the same options to `sessionReplay.plugin()`:

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

const replay = sessionReplayPlugin({
  crossOriginIframes: {
    enabled: true,
    coordinateChildren: true,
  },
});

amplitude.add(replay);
amplitude.init("AMPLITUDE_API_KEY", { deviceId: "DEVICE_ID" });
```

### Child iframe page

Initialize the SDK with the same `apiKey`, `deviceId`, and `sessionId` as the parent. Enable cross-origin iframes, but don't set `coordinateChildren` on the child:

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

sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId: "DEVICE_ID",
  sessionId: SESSION_ID,
  sampleRate: 1,
  crossOriginIframes: { enabled: true },
});
```

Pass `sessionId` and `deviceId` to the child through the iframe URL query string when you set the iframe `src`.

## Configuration options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `crossOriginIframes.enabled` | `boolean` | `false` | Enables cross-origin iframe recording on the page. Set to `true` on both parent and child pages. |
| `crossOriginIframes.coordinateChildren` | `boolean` | `true` | When `true`, the parent SDK sends start/stop signals to child iframes and keeps their recording lifecycle in sync. Set to `false` to manage child recording yourself. Applies to the parent page only. |

## Privacy

The child page's rrweb instance performs its own DOM serialization. The parent's privacy config (mask levels, block selectors, and so on) doesn't automatically apply inside the iframe. Configure privacy settings independently on each child page.

## Limitations

- **Third-party iframes** (for example, Pardot forms, Stripe, Google Maps, or YouTube) can't be captured. You control only pages where you install the Session Replay SDK.
- **`coordinateChildren: false`** opts out of the parent coordinator. In this mode, the child SDK doesn't start recording until you manage its lifecycle directly.
- **Same-origin iframes** don't require cross-origin configuration, but enabling `crossOriginIframes` on both pages still works.

## Validate your setup

1. Confirm the parent and each child page load the Session Replay SDK with `crossOriginIframes.enabled: true`.
2. Use the same `apiKey`, `deviceId`, and `sessionId` on both pages.
3. Add or navigate to the child iframe after the parent SDK initializes.
4. Interact inside the iframe, then open the session in Amplitude's replay viewer.

For local cross-origin testing, serve the parent and child from different origins (different ports or hostnames). A public HTTPS parent can't embed an `http://localhost` child because of mixed content and browser Local Network Access restrictions.

## Troubleshooting

### The iframe is blank in the live page

| Symptom | Likely cause |
| --- | --- |
| Blank iframe from a public parent | Child URL uses `http://localhost` or another blocked origin. Serve the child over public HTTPS. |
| "Refused to connect" | Child URL is wrong or unreachable. Verify the iframe `src` and that the child origin allows embedding. |
| Placeholder only | Parent didn't inject an iframe yet. Add the iframe in your app after the SDK initializes. |
| Empty iframe in replay | Child page doesn't load Session Replay (for example, a static demo page). Install the SDK on the child with `crossOriginIframes.enabled: true`. |

### The iframe is blank in the replay viewer

| Symptom | Likely cause |
| --- | --- |
| Short session looks empty | The first child merge may arrive ~1 second after iframe injection. Record a longer session and interact inside the iframe. |
| Missing styles or low contrast | CSS didn't replay correctly — not missing DOM. Check external stylesheets, add `crossorigin="anonymous"` on `<link rel="stylesheet">`, and allow `app.amplitude.com` in CORS. Go to [CSS styling doesn't appear in replay](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#css-styling-doesnt-appear-in-a-replay). |
| iframe shell with no content | Child DOM merged through incrementals but a later checkout snapshot may omit iframe children. If capture looks correct in raw events but replay shows an empty frame, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) with the session replay ID. |

## Related documentation

- [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin)
- [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk)
- [Session Replay ingestion monitor](https://amplitude.com/docs/session-replay/ingestion-monitor)

================================================================================
# Implement Session Replay with Google Tag Manager
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager
Updated: 2026-09-15
================================================================================

# Implement Session Replay with Google Tag Manager

Instrumenting Amplitude Session Replay with Google Tag Manager requires a different procedure than the standard [Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin).

> **Note:**
>
> This article applies to client-side GTM instrumentations only.

## Enable Session Replay

To instrument Session Replay with Google Tag Manager:

1. Add the [Google Tag Manager Web Template for Amplitude Analytics Browser SDK](https://amplitude.com/docs/data/source-catalog/google-tag-manager) if you haven't enabled it.

> **Note:** Update the Amplitude tag template
>
> The latest version of the Amplitude Analytics Browser SDK template includes a Session Replay toggle.

2. In Google Tag Manager, create a new tag using the Amplitude template, or edit an existing tag based on the template.
3. In the tag's _Initialization_ section, select **Enable Session Replay Plugin**.
4. In Amplitude, navigate to _Organization Settings > Session Replay Settings_. Update any [masking](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#mask-on-screen-data), [sample rate](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#sampling-rate), or other settings.

## Troubleshooting

Multiple instantiation of the Amplitude SDKs is a common problem with GTM and other code injection frameworks. Make sure the initialization logic runs only once in your app. Multiple instantiation can happen if:

- More than one "Init Tag" or another custom tag runs Amplitude.
- Another code injection framework (for example, SquareSpace or Bubble) also runs Amplitude.

This template uses the Amplitude Browser SDK Plugin. For troubleshooting help, refer to [Troubleshooting | Session Replay Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#troubleshooting).

================================================================================
# Session Replay Wrapper for Rudderstack
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-rudderstack-integration
Updated: 2026-11-04
================================================================================

# Session Replay Wrapper for Rudderstack

Amplitude provides a wrapper for integrating Rudderstack and Amplitude's Session Replay.

> **Note:**
>
> This integration snippet supports [Rudderstack Cloud-mode](https://www.rudderstack.com/docs/destinations/rudderstack-connection-modes/#cloud-mode).

## Install the wrapper

Use npm or yarn to install the package, which includes the Amplitude Session Replay SDK.

#### npm

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

#### yarn

```bash
yarn add @amplitude/session-replay-browser
```

## Initialize Session Replay with Rudderstack

For information about the `sessionReplayOptions`, refer to the [Session Replay Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) section.

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

amplitude.init("AMPLITUDE_API_KEY", user_id, config).promise.then(() => {
  window.rudderAnalytics.ready(function () {
    const rudderAnonymousId = rudderAnalytics.getAnonymousId();

    sessionReplay.init("AMPLITUDE_API_KEY", {
      deviceId: rudderAnonymousId,
      sessionId: rudderAnalytics.getSessionId(),
      sampleRate: 0.1, // 10% of sessions will be captured
    }).promise;
    sessionReplay.set(rudderAnalytics.getSessionId());
  });
});
```

## How Amplitude links replays to Rudderstack events

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. Amplitude sends this event directly to link replays with your analytics data. If you don't see this event in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Required field mapping

Amplitude maps the [Rudderstack Anonymous ID](https://www.rudderstack.com/docs/event-spec/standard-events/identify/#anonymous-id) to the [Amplitude Device ID](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#instrumentation-basics), and the [Rudderstack Session ID](https://www.rudderstack.com/docs/sources/event-streams/sdks/session-tracking/) to the [Amplitude Session ID](https://amplitude.com/docs/data/sources/instrument-track-sessions#how-amplitude-defines-sessions). If you use another field for device ID, contact [Amplitude Support](https://support.amplitude.com).

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the `deviceId` value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Rudderstack's anonymous ID is a UUID, which always complies with these requirements. If you use a custom value for `deviceId`, ensure it follows the accepted character set. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshooting

> **Warning:** Session replay and ad blockers
>
> Session Replay isn't compatible with ad blocking software.

For troubleshooting information, go to [Session Replay Standalone SDK | Troubleshooting](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting).

================================================================================
# Session Replay Plugin for Segment
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-wrapper-for-segment
Updated: 2026-11-04
================================================================================

# Session Replay Plugin for Segment

Amplitude provides a plugin that enables a one-line integration between Segment and Amplitude's Session Replay.

> **Note:**
>
> This plugin supports [Segment's Amplitude (Actions)](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/) destination only.
>
> To use Session Replay with [Segment's Amplitude (Classic) destination](https://segment.com/docs/connections/destinations/catalog/amplitude/), use the [Session Replay Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk).

## Install the plugin

Use npm or Yarn to install the package, which includes the Amplitude Session Replay SDK.

#### npm

```bash
npm install @amplitude/segment-session-replay-plugin --save
```

#### yarn

```bash
yarn add @amplitude/segment-session-replay-plugin
```

## Use

For information about the `sessionReplayOptions`, go to the [Session Replay Standalone SDK configuration](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#configuration) section.

```js
import { AnalyticsBrowser } from "@segment/analytics-next";
import { createSegmentActionsPlugin } from "@amplitude/segment-session-replay-plugin";

export const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: SEGMENT_API_KEY,
});

const segmentActionsPlugin = createSegmentActionsPlugin({
  segmentInstance: segmentAnalytics,
  amplitudeApiKey: "AMPLITUDE_API_KEY",
  sessionReplayOptions: {
    logLevel: 4,
    sampleRate: 1,
    debugMode: true,
  },
});

segmentAnalytics.register(segmentActionsPlugin);
```

## Segment plugin architecture

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. The plugin sends this event directly to Amplitude to link replays with your analytics data. If you don't see this event in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## User ID to Device ID mapping

Following Segment's documentation, the plugin maps the Segment user ID to the Amplitude device ID. To find the device ID for replay captures, the plugin checks whether `userId` is set, and if not, the plugin uses `anonymousId`.

The session replay ID uses the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the device ID value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Segment's `userId` and `anonymousId` values are UUIDs, which always comply with these requirements. If you need an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshooting

> **Warning:** Session replay and ad blockers
>
> Session Replay isn't compatible with ad blocking software.

For troubleshooting information, go to [Session Replay Standalone SDK | Troubleshooting](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting).

================================================================================
# Session Replay integration with Segment
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-integration-with-segment
Updated: 2026-11-04
================================================================================

# Session Replay integration with Segment

Session Replay supports other analytics providers. Use the following options to add Session Replay to a Segment-instrumented site.

- [Amplitude (Actions) destination](#amplitude-actions-destination).
- [Amplitude Classic destination (Device-mode)](#amplitude-classic-destination-device-mode).
- [Amplitude Classic destination (Cloud-mode)](#amplitude-classic-destination-cloud-mode).
- [Troubleshoot Segment integration](#troubleshoot-segment-integration).

> **Note:** Replay Captured event
>
> Amplitude creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. Amplitude receives this event directly, and Segment doesn't forward it. If this event doesn't appear in Amplitude, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Amplitude (Actions) destination

Amplitude (Actions) tracks sessions automatically. When a user starts a new session, Amplitude sets an `analytics_session_id` cookie on the user's browser. Configure your implementation to listen for changes to `analytics_session_id` using Segment's [Source Middleware](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/middleware/).

The following code snippet configures Session Replay with Segment's Amplitude (Actions) integration and updates the session ID when `analytics_session_id` changes.

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

const API_KEY = 'AMPLITUDE_API_KEY' // must match that saved with Segment
const getStoredSessionId = () => {
 return cookie.get("analytics_session_id") || 0;
}

const user = await segmentAnalytics.user();
const storedSessionId = getStoredSessionId();

await sessionReplay.init(API_KEY, { 
  sessionId: storedSessionId,
  deviceId: user.anonymousId()
}).promise;

// Add middleware to check if the session id has changed, 
// and update the session replay instance
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
  const storedSessionId = getStoredSessionId();
  const nextSessionId = payload.obj.integrations['Actions Amplitude'].session_id || 0
  if (storedSessionId < nextSessionId) {
    cookie.set("analytics_session_id", nextSessionId);
    sessionReplay.setSessionId(nextSessionId);
  }
  next(payload);
});
```

## Amplitude Classic destination (Device-mode)

This version of the Amplitude destination installs the Amplitude JavaScript SDK (5.2.2) on the client and sends events directly to `api.amplitude.com`.

The Device-mode integration tracks sessions by default because it includes the amplitude-js SDK. The included SDK version (5.2.2) doesn't emit an event for session changes. Use Segment's middleware to update Session Replay when the session ID changes.

```javascript
import * as sessionReplay from "@amplitude/session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

const API_KEY = 'AMPLITUDE_API_KEY' // must match that saved with Segment
const getAmpSessionId = () => {
  const sessionId = window.amplitude.getInstance().getSessionId();
  cookie.set("analytics_session_id", sessionId);
  return sessionId;
};

// Wait for the amplitude-js SDK to initialize,
// then initialize session replay with the correct device id and session id
window.amplitude.getInstance().onInit(() => {
  const sessionId = getAmpSessionId();
  sessionReplay.init(API_KEY, {
    deviceId: window.amplitude.getInstance().options.deviceId,
    sessionId: getAmpSessionId(),
  });
});

// Add middleware to check if the session id has changed, 
// and update the session replay instance
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
  const nextSessionId = window.amplitude.getInstance().getSessionId();
  const storedSessionId = cookie.get("analytics_session_id") || 0;
  if (storedSessionId < nextSessionId) {
    cookie.set("analytics_session_id", nextSessionId);
    sessionReplay.setSessionId(nextSessionId);
  }
  next(payload);
});
```

## Amplitude Classic destination (Cloud-mode)

This version of the Amplitude destination sends events to Segment's backend, which forwards them to Amplitude. The Cloud-mode destination doesn't track sessions by default. Use the Browser SDK as a shell to manage sessions, and use Session Replay as a plugin, as shown in the following example.

```javascript
import { sessionReplayPlugin } from "@amplitude/plugin-session-replay-browser";
import { AnalyticsBrowser } from "@segment/analytics-next";

const segmentAnalytics = AnalyticsBrowser.load({
  writeKey: "segment-key",
});

// A plugin must be added so that events sent through Segment will have
// session replay properties and the correct session id
const segmentPlugin = () => {
  return {
    name: "segment",
    type: "destination",
    execute: async (event) => {
      const properties = event.event_properties || {};
      segmentAnalytics.track(event.event_type, properties, {
        integrations: {
          Amplitude: {
            session_id: amplitude.getSessionId(),
          },
        },
      });
      return {
        code: 200,
        event: event,
        message: "OK",
      };
    },
  };
}; 

const API_KEY = 'AMPLITUDE_API_KEY' // must match that saved with Segment

// Add the session replay plugin first, then the segment plugin
await amplitude.add(sessionReplayPlugin()).promise;
await amplitude.add(segmentPlugin()).promise;

const user = await segmentAnalytics.user();
await amplitude.init(API_KEY, { 
  instanceName: 'session-replay',
  sessionTimeout: Number.MAX_SAFE_INTEGER,
  defaultTracking: false,
  deviceId: user.anonymousId()
}).promise;
amplitude.remove('amplitude');
// Events must be tracked through the shell Browser SDK to properly attach
// session replay properties
amplitude.track('event name')
```

## Device ID and session ID character constraints

The session replay ID has the format `<deviceId>/<sessionId>`. Because Session Replay uses `/` as a delimiter, the `deviceId` value can't contain `/`. Accepted characters: `a-z A-Z 0-9 _ - . | @ : =`. Segment's `anonymousId()` returns a UUID, which always meets these requirements. If you use a custom value for `deviceId`, ensure it follows the accepted character set. To request an additional character, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Troubleshoot Segment integration

If the instance returns empty, your Segment middleware may not have populated the values for the Amplitude integration field `payload.obj.integrations['Actions Amplitude']`. If this happens, add the following `setTimeout` wrapper to ensure the field populates with a valid value.

```js
segmentAnalytics.addSourceMiddleware(({ payload, next, integrations }) => {
    const storedSessionId = getStoredSessionId()
    setTimeout(() => { 
      ... // Rest of the Segment integrations code
    }, 0) 
    next(payload)
});
```

================================================================================
# Session Replay iOS Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin
Updated: 2026-11-05
================================================================================

# Session Replay iOS Plugin

- **Package:** `AmplitudeSessionReplay` ([cocoapods](https://cocoapods.org/pods/AmplitudeSessionReplay))
- **Latest version:** 0.17.0

This article covers how to install Session Replay using the iOS plugin. If your app already uses the Amplitude [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started) or legacy Amplitude [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk), use this option.

If you use Segment through their Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

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-ios-standalone-sdk).

> **Info:** Unified SDK
>
> Install the [Unified SDK for Swift](https://amplitude.com/docs/sdks/analytics/ios/unified-sdk/get-started) to access Session Replay along with other Amplitude products (Analytics, Experiment). The Unified SDK provides a single entry point for all Amplitude features and simplifies integration by handling initialization and configuration of all components.

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree, including the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each view change as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original view tree in sequential order to construct the replay. Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The method you use depends on the version of the Amplitude iOS SDK you use.

#### iOS Swift SDK

The Session Replay iOS Plugin requires that:

1. Your application runs on iOS or iPadOS.
2. You use `1.9.0` or higher of the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started).

#### iOS SDK (maintenance)

The Session Replay Middleware requires that:

1. Your application runs on iOS or iPadOS.
2. You use `8.22.0` or higher of the [(maintenance) Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk).
3. You can provide a device ID to the SDK.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies.

#### Swift SDK

**Swift Package Manager**

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]
```

For integrating with `Amplitude-Swift`, use the `AmplitudeSwiftSessionReplayPlugin` target.

```swift
.product(name: "AmplitudeSwiftSessionReplayPlugin", package: "AmplitudeSessionReplay")
```

**CocoaPods**

Add the core library and the plugin to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
pod 'AmplitudeSwiftSessionReplayPlugin', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
```

**Configure your application code**

```swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin

// Initialize Amplitude Analytics SDK instance
let amplitude = Amplitude(configuration: Configuration(apiKey: "AMPLITUDE_API_KEY"))

// Create and Install Session Replay Plugin
// Recording will be handled automatically
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0))
```

#### Legacy SDK

**Swift Package Manager**

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]
```

For integrating with `Amplitude-iOS`, use the `AmplitudeiOSSessionReplayMiddleware` target.

```swift
.product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay")
```

**CocoaPods**

Add the core library and the middleware to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
pod 'AmplitudeiOSSessionReplayMiddleware', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
```

**Configure your application code**

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Initialize Amplitude Analytics SDK instance

let amplitude = Amplitude.instance()

// Although not required, we recommend enabling session start and end events when enabling Session Replay
amplitude.defaultTracking.sessions = true

// Create and Install Session Replay Middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1))

amplitude.initializeApiKey("AMPLITUDE_API_KEY")
```

## Configuration

Pass the following option when you initialize the Session Replay plugin:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions Amplitude selects for replay collection. The value 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. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration ](#remote-configuration) for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Sets the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Sets the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when and where Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). Use `UploadConfig(serverUrl:)` to send uploads to your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests) (version 0.14.0 or later). |

### Custom session IDs

Session Replay for iOS version 0.11.2 and later supports string session IDs, for example UUIDs, through the `customSessionId` property. Use a custom session ID if your project defines sessions with a custom event property instead of the Amplitude `session_id`.

When you set `customSessionId`, the value takes precedence over the session ID that the plugin syncs from the Amplitude SDK. Set the property to `nil` to resume using the Amplitude session ID.

```swift
// Keep a reference to the plugin to set the custom session ID
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0)
sessionReplayPlugin.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
amplitude.add(plugin: sessionReplayPlugin)

// Whenever your custom session changes
sessionReplayPlugin.customSessionId = NEW_CUSTOM_SESSION_ID
```

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Change masking at runtime

Set `privacyConfig` on the plugin to change the automatic masking level while the app runs. Set it before or after you add the plugin to Amplitude.

```swift
sessionReplayPlugin.privacyConfig = PrivacyConfig(maskLevel: .conservative)
```

If Remote Config supplies a masking level, it takes precedence. The plugin retains the local `privacyConfig` value and applies it when Remote Config doesn't supply a masking level or when you disable Remote Config.

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

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

```swift
// Set optOut on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: "AMPLITUDE_API_KEY",
                                                           optOut: true,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))
```

### 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:

```swift
// Set serverZone on the Amplitude SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: "AMPLITUDE_API_KEY",
                                                           serverZone: .EU,
                                                           /* other configuration */))
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */))
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```swift
// This configuration samples 1% of all sessions
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.01))
```

### Targeted Replay Capture

Session Replay iOS Plugin 0.15.0 and later supports [Targeted Replay Capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) (TRC), which captures only the sessions that match conditions you set in Session Replay settings. The plugin evaluates those conditions against each event and the user's properties from the iOS Swift SDK, so TRC needs no extra code. Event, event property, and user property conditions apply to iOS; Page URL conditions don't.

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .automatic
))

// Or set a fixed profile (low, medium, or high)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(
    sampleRate: 0.1,
    quality: .medium
))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device is on a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
// Set uploadConfig through the plugin's Config initializer
let config = AmplitudeSwiftSessionReplayPlugin.Config(
    sampleRate: 0.1,
    uploadConfig: UploadConfig(disableMeteredUploads: true)
)
amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(config: config))
```

### Disable replay collection

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

- The user leaves your app.
- You call `sessionReplayPlugin.stop()`.
- You remove the plugin from the SDK with `amplitude.remove(plugin: sessionReplayPlugin)`.

Call `sessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the SessionReplayPlugin instance `let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(/* session replay options */)`.

Call `sessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the plugin once, without starting capture
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0, autoStart: false)
amplitude.add(plugin: sessionReplayPlugin)

// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()

// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()
```

You can also use a feature-flag product such as [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria such as location. For example, you can create a feature flag that targets a specific user group, and add that to your initialization logic:

```swift
import AmplitudeSwift
import AmplitudeSwiftSessionReplayPlugin

// Your existing initialization logic with Amplitude-Swift SDK
let amplitude = Amplitude(configuration: Configuration(apiKey: "AMPLITUDE_API_KEY",
                                                           /* other configuration */))

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.1)
  amplitude.add(plugin: sessionReplayPlugin)
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay iOS Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk
Updated: 2026-11-05
================================================================================

# Session Replay iOS Standalone SDK

- **Package:** `AmplitudeSessionReplay` ([cocoapods](https://cocoapods.org/pods/AmplitudeSessionReplay))
- **Latest version:** 0.17.0

This article covers how to install Session Replay for iOS using the standalone SDK. Choose this option if you use a provider other than Amplitude for in-product analytics.

If your app already uses an [Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started), use the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin) instead.

If you use Segment through the Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The Session Replay Standalone SDK requires that:

1. Your application runs on iOS or iPadOS.
2. You track sessions with a timestamp or a custom string session ID that you can pass to the SDK. You inform the SDK whenever the session identifier changes.
3. You can provide a device ID to the SDK.
4. The `Session ID` and `Device ID` you pass to the Standalone SDK match those sent as event properties to Amplitude.

The Standalone SDK doesn't provide session management. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of Session Replay to your project dependencies.

#### SPM

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]
```

To integrate with third-party analytics, use the `AmplitudeSessionReplay` target.

```swift
.product(name: "AmplitudeSessionReplay", package: "AmplitudeSessionReplay")
```

#### CocoaPods

Add Session Replay to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
```

Configure your application code.

1. Create a `SessionReplay` instance. Pass the API key, and a session identifier and device identifier if available.
2. Call `sessionReplay.start()` to begin capturing replays. The standalone SDK doesn't start capture automatically, so you must call `start()` once you set the device and session identifiers.
3. When the session identifier or device identifier changes, pass the new value to Amplitude with `sessionReplay.sessionId` or `sessionReplay.deviceId`, respectively. For string session IDs, use `sessionReplay.customSessionId` instead. Refer to [Custom session IDs](#custom-session-ids).
4. Collect Session Replay properties to send with other event properties using `sessionReplay.additionalEventProperties`.

```swift
import AmplitudeSessionReplay
import ThirdPartyAnalytics

// Initialize the standalone session replay SDK
let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 0.1)

// Start capturing replays. The standalone SDK doesn't start automatically.
sessionReplay.start()

// Track an event
// Get session replay properties for this session
var eventProperties = event.eventProperties ?? [:]
eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current }
event.eventProperties = eventProperties
ThirdPartyAnalytics.track(event)

// Handle session ID changes
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.sessionId = ThirdPartyAnalytics.getSessionId()

// Handle device ID changes
// Whenever the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
// Update the device ID in session replay
sessionReplay.deviceId = ThirdPartyAnalytics.getDeviceId()
```

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | n/a | Sets the Amplitude API key. |
| `deviceId` | `String` | No | `nil` | Sets an identifier for the device running your application. Set it before `start()` to associate replay data with the device. |
| `sessionId` | `Int64` | No | `-1` | Sets an identifier for the user's current session. Set it before `start()` to associate replay data with the session. The value must use milliseconds since epoch (Unix timestamp). To use a string session ID instead, set the `customSessionId` property after initialization. Refer to [Custom session IDs](#custom-session-ids). |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, to set the fraction of sessions Amplitude randomly selects. Over a large number of sessions, `0.4` selects 40% of those sessions. |
| `optOut` | `Bool` | No | `false` | Sets permission to collect replays for sessions. A value of `true` prevents Amplitude from collecting session replays. |
| `logger` | `CoreLogger?` | No | `nil` | Sets a custom logger to emit log messages to a destination you choose. When `nil`, Session Replay logs errors through an OS logger. |
| `serverZone` | `ServerZone` | No | `.US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Configures the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Configures the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when and where Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). Use `UploadConfig(serverUrl:)` to send uploads to your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests) (version 0.14.0 or later). |

### Custom session IDs

Session Replay for iOS version 0.11.2 and later supports string session IDs, for example UUIDs, through the `customSessionId` property. Use a custom session ID if your project defines sessions with a custom event property instead of a timestamp-based `session_id`.

The initializer accepts only a numeric `sessionId`. To use a string value, set `customSessionId` on the instance after you create it, and update it whenever your custom session changes:

```swift
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     deviceId: DEVICE_ID,
                                     sampleRate: 0.1)

// Set a string session ID instead of the numeric sessionId
sessionReplay.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
sessionReplay.start()

// Whenever your custom session changes
sessionReplay.customSessionId = ThirdPartyAnalytics.getCustomSessionId()
```

`sessionId` and `customSessionId` are two views of the same underlying value, which the SDK stores as a string:

- Setting `sessionId` replaces the current custom session ID with the numeric value. When you use custom session IDs, update `customSessionId` instead of `sessionId` whenever the session changes.
- When the stored value isn't numeric, the `sessionId` property returns `-1`. Read `customSessionId` to get the current value.
- Setting a different value ends the current replay and starts a new one.

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Change masking at runtime

Set `privacyConfig` to change the automatic masking level while the app runs.

```swift
sessionReplay.privacyConfig = PrivacyConfig(maskLevel: .conservative)
```

If Remote Config supplies a masking level, it takes precedence. The SDK retains the local `privacyConfig` value and applies it when Remote Config doesn't supply a masking level or when you disable Remote Config.

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

Session Replay provides an opt-out configuration option. Passing `optOut: true` during initialization prevents Amplitude from collecting session replays. For example:

```swift
// Pass a boolean value to indicate a user's opt-out status
        let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                             optOut: true,
                                             /* other session replay options */)
```

### 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:

```swift
// Set serverZone to EU
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     serverZone: .EU,
                                     /* other session replay options */)
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```swift
// This configuration samples 1% of all sessions
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     sampleRate: 0.01,
                                     /* other session replay options */)
```

### Targeted Replay Capture

Session Replay iOS standalone SDK 0.15.0 and later supports [Targeted Replay Capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) (TRC), which captures only the sessions that match conditions you set in Session Replay settings. The standalone SDK doesn't receive your analytics events, so pass events and the user's properties to Session Replay:

- Call `evaluateTargeting(userProperties:)` with the user's complete set of properties right after you create the `SessionReplay` instance, and again whenever the properties change. Each call replaces the properties from the previous call.
- Call `evaluateTargeting(eventType:eventProperties:)` for each event, before you add `additionalEventProperties` to the event. This order lets Session Replay tag the event that matches a condition.

```swift
// Right after you create the instance, and whenever the user's properties change
sessionReplay.evaluateTargeting(userProperties: ["plan": "Pro"])

// For each event, before you add the Session Replay properties
sessionReplay.evaluateTargeting(eventType: event.eventType,
                                eventProperties: event.eventProperties)
var eventProperties = event.eventProperties ?? [:]
eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current }
event.eventProperties = eventProperties
ThirdPartyAnalytics.track(event)
```

Event, event property, and user property conditions apply to iOS; Page URL conditions don't.

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and image resolution. Higher profiles use a higher frame rate and resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .automatic,
                                     /* other session replay options */)

// Or set a fixed profile (low, medium, or high)
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     quality: .medium,
                                     /* other session replay options */)
```

You can also change the profile for an existing standalone instance:

```swift
sessionReplay.quality = .medium
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
let sessionReplay = SessionReplay(apiKey: "AMPLITUDE_API_KEY",
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     uploadConfig: UploadConfig(disableMeteredUploads: true),
                                     /* other session replay options */)
```

### Disable replay collection

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

- The user leaves your app.
- You call `sessionReplay.stop()`.

Call `sessionReplay.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

Call `sessionReplay.start()` to re-enable replay collection when the user returns to an unrestricted area of your app. Because `start()` and `stop()` resume and pause capture on the same instance, you can call them on screen transitions to record only the screens you choose.

### Flush recorded data

Call `flush()` to ask the standalone SDK to flush recorded replay data. This is useful when your host analytics client flushes and you want to flush Session Replay at the same point.

```swift
sessionReplay.flush()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) 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:

```swift
import AmplitudeSessionReplay
import ThirdPartyAnalytics

let sessionReplay = SessionReplay(apiKey: amplitude.apiKey,
                                     deviceId: DEVICE_ID,
                                     sessionId: SESSION_ID,
                                     sampleRate: 1.0)

if (nonEUCountryFlagEnabled) {
    sessionReplay.start()
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

### Multiple Amplitude instances

Session Replay supports attaching to a single instance of the Amplitude SDK. If you have more than one instance instrumented in your application, make sure to start Session Replay on the instance that most relates to your project.

### 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 the `[Amplitude] End Session` occurs, but before the iOS SDK and Session Replay middleware can process it. When the user uses the app again, the SDK and middleware 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 don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- No events triggered through the iOS SDK in the current session
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### No events triggered through the iOS 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. If you instrument your events with an analytics provider other than Amplitude, the iOS SDK may send only the default Session Start and Session End events, which don't include this property.

For local testing, you can force a Session Start event to ensure that Session Replay functions.

1. In Amplitude, in the User Lookup Event Stream, you should see a Session Start event that includes the `[Amplitude] Session Replay ID` property. After processing, the Play Session button should appear for that session.

#### Sampling

As mentioned above, the default `sampleRate` for Session Replay is `0`. Update the rate to a higher number. For more information see, [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. Reasons why `[Amplitude] Session Replay ID`  may not be present in an event include:

- The user may have opted out or the session may not be part of the sample set given the current `sampleRate`. Increasing the `sampleRate` captures more sessions.
- Amplitude events may still send through your provider, but `additionalEventProperties` doesn't return the `[Amplitude] Session Replay ID` property. This can result from `optOut` and `sampleRate` configuration settings. Check that `optOut` and `sampleRate` are set to include the session.

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-iOS).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

================================================================================
# Session Replay iOS Segment Integration
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration
Updated: 2026-11-05
================================================================================

# Session Replay iOS Segment Integration

This article covers installation of Session Replay using the Session Replay iOS Segment plugin. Use this option if your app uses Segment's Analytics-Swift library and Amplitude (Actions) destination.

If your app uses an [Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started), use the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin).

If you use Segment with other options, choose the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-standalone-sdk).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree: the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each change as a diff. When you watch the replay, Session Replay applies each diff back to the original view tree in sequential order. Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).

## Before you begin

The Session Replay iOS Segment Plugin requires that:

1. Your application runs on iOS or iPadOS.
2. You use Segment's Analytics-Swift library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's [Amplitude Plugin](https://segment.com/docs/connections/sources/catalog/libraries/mobile/apple/destination-plugins/amplitude-swift/).

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies.

The Segment plugin is available through Swift Package Manager only. Add Session Replay as a dependency in your Package.swift file or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]
```

To integrate with `Analytics-Swift`, use the `AmplitudeSegmentSessionReplayPlugin` target.

```swift
.product(name: "AmplitudeSegmentSessionReplayPlugin", package: "AmplitudeSessionReplay")
```

Configure your application code:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Initialize Segment
let analytics = Analytics(configuration: config)

// Ensure Segment's AmplitudeSession plugin is added before AmplitudeSegmentSessionReplayPlugin
analytics.add(plugin: AmplitudeSession())

// Initialize AmplitudeSegmentSessionReplayPlugin with your Amplitude API key
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                              sampleRate: 0.1))
```

## Configuration

Pass the following option when you initialize the Session Replay plugin:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `amplitudeApiKey` | `String` | Yes | n/a | Sets the Amplitude API key. The Segment plugin requires this value to send replays to Amplitude. |
| `sampleRate` | `Float` | No | `0` | Use this option to control how many sessions to select for replay collection. The number should be a decimal between 0 and 1 (for example, `0.4`), representing the fraction of sessions to have randomly selected for replay collection. Over a large number of sessions, `0.4` would select `40%` of those sessions. |
| `serverZone` | `ServerZone` | No | `.US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in EU data center. |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration ](#remote-configuration) for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Use this option to configure the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Use this option to configure the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when and where Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). Use `UploadConfig(serverUrl:)` to send uploads to your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests) (version 0.14.0 or later). |

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> When you enable remote configuration, settings you define in Amplitude take precedence over settings you define locally in the SDK. As a result, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

Set `optOut` on the plugin to indicate that a user opted out of session replay.

```swift
// Pass a boolean value to indicate a users opt-out status
amplitudeSegmentSessionReplayPlugin.optOut = true
```

### 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:

```swift
// Set serverZone on the AmplitudeSegmentSessionReplayPlugin
let plugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                     sampleRate: 0.1,
                                                     serverZone: .EU)
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```swift
// This configuration samples 1% of all sessions
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                              sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device. For example, the SDK selects high on newer devices and lower on older ones.

```swift
// Use automatic profile selection based on device
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                              sampleRate: 0.1,
                                                              quality: .automatic))

// Or set a fixed profile (low, medium, or high)
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                              sampleRate: 0.1,
                                                              quality: .medium))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                              sampleRate: 0.1,
                                                              uploadConfig: UploadConfig(disableMeteredUploads: true)))
```

### Disable replay collection

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

- The user leaves your app.
- You call `amplitudeSegmentSessionReplayPlugin.stop()`.
- You remove the plugin from Segment with `analytics.remove(plugin: amplitudeSegmentSessionReplayPlugin)`.

Call `amplitudeSegmentSessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> Keep a reference to the SessionReplayPlugin instance: `let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(/* session replay options */)`.

Call `amplitudeSegmentSessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the plugin once, without starting capture
let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY",
                                                                              sampleRate: 1.0,
                                                                              autoStart: false)
analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)

// Start capture when the user enters a screen you want to record
amplitudeSegmentSessionReplayPlugin.start()

// Stop capture when the user leaves that screen
amplitudeSegmentSessionReplayPlugin.stop()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) 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, then add that flag to your initialization logic:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Your existing initialization logic with Segment
let analytics = Analytics(configuration: config)
analytics.add(plugin: AmplitudeSession())

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: "AMPLITUDE_API_KEY", sampleRate: 0.1)
  analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)
}
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay iOS Middleware
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-ios-middleware
Updated: 2026-11-05
================================================================================

# Session Replay iOS Middleware

> **Alpha:** Early access SDK
>
> As an Alpha release, this SDK may contain bugs and cause crashes. Before you enable in production, thoroughly test your app in a controlled environment. For more information about best practices for developer preview SDKs, see [SDK Maintenance and Support](https://amplitude.com/docs/sdks/sdk-maintenance-and-support#sdk-major-version-life-cycle).

This article covers Session Replay installation through the [iOS SDK middleware](https://amplitude.com/docs/sdks/sdk-middleware). If your app already uses the [(maintenance) Amplitude SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk), use this option.

If your app already uses the [(latest) iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk/get-started), choose the [Session Replay iOS SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-plugin).

If you use Segment through their Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-ios-segment-integration).

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-ios-standalone-sdk).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the iOS apps in which it's installed by:
>
> - Asynchronously processing replay data, to avoid blocking the main user interface thread. The main thread must be used to interact with the view hierarchy, but all processing is performed on a background queue.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Before you begin

The Session Replay Middleware requires that:

1. Your application runs on iOS or iPadOS.
2. You use `8.22.0` or higher of the [(maintenance) Amplitude iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-sdk).
3. You can provide a device ID to the SDK.

### Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the middleware to your project dependencies.

#### SPM

Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.17.0")
]
```

For integrating with `Amplitude-iOS`, use the `AmplitudeiOSSessionReplayMiddleware` target.

```swift
.product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay")
```

#### CocoaPods

Add the core library and the middleware to your Podfile.

```plaintext
pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
pod 'AmplitudeiOSSessionReplayMiddleware', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.17.0'
```

Configure your application code:

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Initialize Amplitude Analytics SDK instance

let amplitude = Amplitude.instance()

// Although not required, we recommend enabling session start and end events when enabling Session Replay
amplitude.defaultTracking.sessions = true

// Create and Install Session Replay Middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1))

amplitude.initializeApiKey("AMPLITUDE_API_KEY")
```

## Configuration

Pass the following options when you initialize the Session Replay middleware:

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, representing the fraction of sessions randomly selected for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. For more information, refer to [Sampling rate](#sampling-rate). |
| `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables remote configuration for this instance of Session Replay. |
| `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. |
| `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). |
| `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. |
| `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Sets the maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Sets the maximum length of a log message. |
| `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. |
| `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when and where Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). Use `UploadConfig(serverUrl:)` to send uploads to your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests) (version 0.14.0 or later). |

### Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the [Web view support](#web-view-support-beta) section.

#### Mask level

Session Replay for iOS supports three levels of masking, configurable with the `maskLevel` option.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks all passwords, email addresses, credit card numbers, and phone numbers. |
| `medium` | Masks all editable text views. |
| `conservative` | Masks all text views. |

#### Privacy methods for UIKit

Session Replay provides an extension on `UIView` to manage privacy. Import the Session Replay library to access it.

```swift
import AmplitudeSessionReplay
```

| Variable | Description |
| --- | --- |
| `amp_isBlocked` | Set `view.amp_isBlocked` to selectively replace a view and its subviews with a placeholder in session replays. UITextViews and UITextFields are automatically blocked. To unblock a view that is masked by default, set the this value to false |

#### Privacy Modifiers for SwiftUI

Session Replay provides an extension on `View` to manage privacy. Import the Session Replay Library to access it.

```swift
import AmplitudeSessionReplay
```

| Modifier | Description |
| --- | --- |
| `amp_setBlocked(_ blocked: Bool)` | Add the `amp_setBlocked()` modifier to a `View` to selectively replace a view and its subviews with a placeholder in session replays. To unblock a view that is masked by default, set the this value to false |

### User opt-out

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

```swift
// Set optOut on the Amplitude SDK
amplitude.optOut = true
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
```

### 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:

```swift
// Set serverZone on the Amplitude SDK
amplitude.setServerZone(.EU)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */))
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```swift
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones).

```swift
// Use automatic profile selection based on device
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    quality: .automatic
))

// Or set a fixed profile (low, medium, or high)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    quality: .medium
))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device is on a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(
    sampleRate: 0.1,
    uploadConfig: UploadConfig(disableMeteredUploads: true)
))
```

### Disable replay collection

After it's enabled, Session Replay runs on your app until either:

- The user leaves your app.
- You call `sessionReplayMiddleware.stop()`.
- You remove the middleware from the SDK with `amplitude.removeEventMiddleware(sessionReplayMiddleware)`.

Call `sessionReplayMiddleware.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the Session Replay Middleware instance `let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(/* session replay options */)`.

Call `sessionReplayMiddleware.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the middleware with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the middleware once, without starting capture
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 1.0, autoStart: false)
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Start capture when the user enters a screen you want to record
sessionReplayMiddleware.start()

// Stop capture when the user leaves that screen
sessionReplayMiddleware.stop()
```

You can also use a feature flag product like [Amplitude Experiment](https://amplitude.com/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, you can create a feature flag that targets a specific user group and add that to your initialization logic:

```swift
import Amplitude
import AmplitudeiOSSessionReplayMiddleware

// Your existing initialization logic with Amplitude-iOS SDK
let amplitude = Amplitude.instance()

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Middleware
  let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1)
  amplitude.addEventMiddleware(sessionReplayMiddleware)
}

amplitude.initializeApiKey("AMPLITUDE_API_KEY")
```

### Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set `captureWebViews` to `true` in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in [Block on-screen data](#block-on-screen-data).

```swift
// UIKit
webView.amp_isBlocked = false
```

### Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture,  unmask the map view in your implementation.

```swift
// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)
```

### Log Recording

> **Note:** Availability
>
> AmplitudeSessionReplay `0.8.0` and later support log recording.

Session Replay supports recording logs in iOS applications. Configure the limits with `recordLogOptions` when you initialize the integration, then send log messages through `recordLog(level:message:date:)`.

#### swift

```swift
import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
import AmplitudeSwiftSessionReplayPlugin

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000))
amplitude.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
amplitude.addEventMiddleware(sessionReplayMiddleware)

sessionReplayMiddleware.recordLog(level: .error, message: "This is an error log")
```

#### swift

```swift
let sessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(
    amplitudeApiKey: "AMPLITUDE_API_KEY",
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)
analytics.add(plugin: sessionReplayPlugin)

sessionReplayPlugin.recordLog(level: .error, message: "This is an error log")
```

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### CocoaLumberjack

If you use `CocoaLumberjack`, you can integrate it with a custom logger provider.

```swift
class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

```

#### React Native

If you use `console` log or `react-native-logs` with `consoleTransport`, you can integrate it with `RCTAddLogFunction`.

```swift
RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay cannot capture the following iOS views:

  - Out-of-process iOS views, such as SFSafariViewController
  - AVPlayerLayer backed views

================================================================================
# Session Replay Android Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin
Updated: 2026-11-04
================================================================================

# Session Replay Android Plugin

- **Package:** `com.amplitude:plugin-session-replay-android` ([maven](https://search.maven.org/artifact/com.amplitude/plugin-session-replay-android))
- **Latest version:** 0.33.0

The Session Replay Android plugin adds Session Replay to an app that already uses the Amplitude Android SDK. It attaches to your existing SDK instance and captures replays alongside the events you track. If you use a different provider for in-product analytics, use the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone) instead.

> **Info:** Unified SDK
>
> Install the [Unified SDK for Android](https://amplitude.com/docs/sdks/analytics/android/unified-sdk/get-started) to access Session Replay along with other Amplitude products (Analytics, Experiment). The Unified SDK provides a single entry point for all Amplitude features and simplifies integration by handling initialization and configuration of all components.

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

Session Replay captures changes to an app's view tree. The view tree includes the main view and all child views recursively. 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 app's view tree. As the user interacts with the app, Session Replay captures each change to the view as a diff. Session Replay then constructs the replay of the session by applying each diff to the original view tree in sequential order.

Session replays have no maximum length.

> **Tip:** Report issues
>
> To report issues with Session Replay for Android, go to the [AmplitudeSessionReplay-Android GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

## Prerequisites

The method you use depends on the version of the Amplitude Android SDK you use.

#### Android-Kotlin

If you use the current [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/get-started), follow the instructions for the Android Plugin.

The Session Replay Android plugin requires that:

1. Your application is Android-based.
2. You can provide a device identifier to the SDK.

#### Android (maintenance)

If you use the [maintenance Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk), use the instructions for Android Middleware.

The Session Replay Middleware requires that:

1. Your application is Android-based.
2. You use `2.40.1` or higher of the [(maintenance) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

#### Kotlin SDK

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/plugin-session-replay-android/versions) of the plugin to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:plugin-session-replay-android:0.33.0")
// You will also need the Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:analytics-android:[1.30.0,2.0.0)")
```

Configure your application code:

```kotlin
import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin

// Initialize Amplitude Analytics SDK instance
val amplitude = Amplitude("AMPLITUDE_API_KEY", applicationContext)

// Create and Install Session Replay Plugin
// Recording will be handled automatically
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    sampleRate = 1.0
)
amplitude.add(sessionReplayPlugin)
```

#### Legacy SDK

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/middleware-session-replay-android/versions) of the session replay middleware to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:middleware-session-replay-android:0.26.1")
// You will also need the (maintenance) Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:android-sdk:[2.40.1,3.0.0)")
```

Configure your application code.

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Initialize (maintenance) Amplitude Analytics SDK instance
val amplitude = Amplitude.getInstance()
    .initialize(this, "AMPLITUDE_API_KEY")
    // Replay events will be flushed on close as well
    // If setFlushEventsOnClose(false) you must call flush() manually
    .setFlushEventsOnClose(true)

// Create Session Replay Middleware
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0)

// Add session replay middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Track events
amplitude.logEvent("Setup (maintenance) Amplitude Android SDK with session replay!")

// Send replay events to the server
amplitude.uploadEvents()

// You can also call flush() on the middleware directly to only send replay events
// sessionReplayMiddleware.flush()

// Always flush before app exit (onPause)
// override fun Activity.onPause() { sessionReplayMiddleware.flush() }
```

> **Info:** Sample rate
>
> The sample rate in these code samples is `1.0`. This setting ensures Amplitude captures sessions during testing, but can cause overages in production.

## Configuration

Pass the following options when you initialize the Session Replay plugin.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views Session Replay masks. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. Refer to [Mask level](#mask-level). |
| `serverUrl` | `String?` | No | `null` | Advanced. Full URL that Session Replay uploads data to, for example your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests). Overrides `serverZone`. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | Advanced. Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | Advanced. Local storage limit, in MB. |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when the plugin initializes. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Custom session IDs

Session Replay for Android version 0.26.4 and later supports string session IDs, for example UUIDs, through the `setCustomSessionId` method. Use a custom session ID if your project defines sessions with a custom event property instead of the Amplitude `session_id`.

When you set a custom session ID, the value takes precedence over the session ID that the plugin syncs from the Amplitude SDK. Pass `null` to clear the override and resume using the Amplitude session ID.

```kotlin
// Keep a reference to the plugin to set the custom session ID
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    sampleRate = 1.0
)
sessionReplayPlugin.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")
amplitude.add(sessionReplayPlugin)

// Whenever your custom session changes
sessionReplayPlugin.setCustomSessionId(newCustomSessionId)
```

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

The Session Replay plugin follows the Android SDK's `optOut` setting. You can also call `setOptOut` and `getOptOut` directly on the plugin instance to pause or resume capture at runtime without restarting the SDK.

```kotlin
// Control opt-out through the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = "AMPLITUDE_API_KEY",
    optOut = true,
    /* other configuration */
))
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    /* session replay options */
)
amplitude.add(sessionReplayPlugin)

// Or pause and resume capture directly on the plugin instance
sessionReplayPlugin.setOptOut(true)   // pause
sessionReplayPlugin.setOptOut(false)  // resume
```

### 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:

```kotlin
// Set serverZone on the Amplitude SDK
val amplitude = Amplitude(Configuration(
    apiKey = "AMPLITUDE_API_KEY",
    serverZone = ServerZone.EU,
    /*, other configuration */
))
amplitude.add(SessionReplayPlugin(
    context = applicationContext,
    /* session replay options */
))
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```kotlin
// This configuration samples 1% of all sessions
amplitude.add(SessionReplayPlugin(
    context = applicationContext,
    sampleRate = 0.01
))
```

### Disable replay collection

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

- The user leaves your app.
- You call `sessionReplayPlugin.stop()`.
- You remove the plugin from the SDK with `amplitude.remove(sessionReplayPlugin)`.

Call `sessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> This requires keeping a reference to the `SessionReplayPlugin` instance: `val sessionReplayPlugin = SessionReplayPlugin(context = applicationContext, /* session replay options */)`.

Call `sessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
// Add the plugin without starting capture
val sessionReplayPlugin = SessionReplayPlugin(
    context = applicationContext,
    sampleRate = 1.0,
    autoStart = false
)
amplitude.add(sessionReplayPlugin)

// Start capture when the user enters a screen you want to record
sessionReplayPlugin.start()

// Stop capture when the user leaves that screen
sessionReplayPlugin.stop()
```

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

```kotlin
import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.android.plugins.SessionReplayPlugin

// Your existing initialization logic with Android SDK
val amplitude = Amplitude(Configuration(apiKey = "AMPLITUDE_API_KEY" /*, ... other configuration */))

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  val sessionReplayPlugin = SessionReplayPlugin(
      context = applicationContext,
      sampleRate = 0.5
  )
  amplitude.add(sessionReplayPlugin)
}
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

Starting in version 0.32.0, Session Replay applies the browser privacy policy to web content inside captured WebViews. Session Replay masks or blocks elements within the WebView according to the same rules that govern browser-based Session Replay, so sensitive fields such as password inputs remain masked even when you unmask the WebView for capture.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out of tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

The SDK stores replay data locally. It retries transient upload failures, subject to retry and storage limits.

Amplitude recommends setting `flushEventsOnClose = true` in the Amplitude SDK Configuration (the default) to send session data to the server on each app exit.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

### Multiple Amplitude instances

Session Replay supports attaching to a single instance of the Amplitude SDK. If you have more than one instance instrumented in your application, start Session Replay on the instance that most relates to your project.

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).                                                                                    |

### 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 the `[Amplitude] End Session` occurs, but before the Android SDK and Session Replay plugin can process it. When the user uses the app 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 don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- The app process ends or you shut down the SDK before pending replay data uploads.
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### Sampling

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

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay isn't implemented on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

### Captured sessions contain limited information

Amplitude automatically creates the `[Amplitude] Replay Captured` event 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.

Reasons this event may not appear include:

- The user opted out or isn't part of the sample set given the current `sampleRate`. Increase the `sampleRate` to capture more sessions.
- You enabled the `optOut` configuration for the session. Check that `optOut` and `sampleRate` settings include the session.
- Your app uses a method other than the Android SDK to instrument events. Consider using the [Session Replay Standalone SDK for Android](https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone/).

If you verify these settings and still don't see the event, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

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

In some scenarios, the length of a replay can exceed the time between the `[Amplitude] Start Session` and `[Amplitude] End Session` events. This situation happens when a user closes the app after the `[Amplitude] End Session` event occurs, but before the Android SDK and Session Replay plugin can process the event. When the user uses the app again, the SDK and plugin process the event and send it to Amplitude with the replay. To verify this scenario, check for a discrepancy between the `End Session Client Event Time` and the `Client Upload Time`.

### Session replays don't appear in Amplitude

Session replays may not appear in Amplitude for these reasons:

- Lack of connectivity. Ensure your app has access to the internet, then try again.
- Failure to flush the recording before exiting the app.
- No events sent through the Android SDK in the current session.
- Missing `[Amplitude] Replay Captured` event. Review [Captured sessions contain limited information](#captured-sessions-contain-limited-information).
- Sampling.

#### Sampling

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

### Session Replay processing errors

Replays typically appear within minutes of ingestion. Delays or errors may result from one or more of the following:

- Mismatching API keys or Device IDs. This mismatch happens when Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a user closes the app within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If you haven't implemented Session Replay on all pages a user visits, the session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

================================================================================
# Session Replay Android Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-standalone
Updated: 2026-11-04
================================================================================

# Session Replay Android Standalone SDK

- **Package:** `com.amplitude:session-replay-android` ([maven](https://search.maven.org/artifact/com.amplitude/session-replay-android))
- **Latest version:** 0.33.0

This article covers how to install Session Replay for Android with the standalone SDK. If you use a provider other than Amplitude for in-product analytics, choose this option. If your app already uses the Amplitude Android SDK, use the [Session Replay Android SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin) instead.

> **Tip:** Report issues
>
> To report issues with Session Replay for Android, go to the [AmplitudeSessionReplay-Android GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Prerequisites

The Session Replay Standalone SDK requires that:

1. Your application is Android-based.
2. You track sessions with a timestamp or a custom string session ID that you can pass to the SDK. Inform the SDK whenever the session identifier changes.
3. You can provide a device ID to the SDK.
4. The session and device IDs you pass to the standalone SDK match the IDs on analytics events you send to Amplitude.

The Standalone SDK doesn't provide session management capabilities. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/session-replay-android/versions) of the Session Replay SDK to your project dependencies.

```kotlin
implementation("com.amplitude:session-replay-android:0.33.0")
```

Configure your application code:

1. Create a `val sessionReplay = SessionReplay()` object to start collecting replays. Pass the API key, session identifier, and device identifier.
2. When the session or device identifier changes, pass the new value to Amplitude with `sessionReplay.setSessionId` or `sessionReplay.setDeviceId`. For string session IDs, use `sessionReplay.setCustomSessionId` instead. Refer to [Custom session IDs](#custom-session-ids).

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics

// Initialize the standalone session replay SDK
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    context = applicationContext,
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    sampleRate = 1.0,
)

// Handle session ID change
// Whenever the session ID changes
ThirdPartyAnalytics.setSessionId(sessionId)
// Update the session ID in session replay
sessionReplay.setSessionId(ThirdPartyAnalytics.getSessionId())

// Handle device ID change
// When the device ID changes
ThirdPartyAnalytics.setDeviceId(deviceId)
//Update the device ID in session replay
sessionReplay.setDeviceId(ThirdPartyAnalytics.getDeviceId())
```

## Configuration

Pass the following configuration options when you initialize the Session Replay SDK.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | n/a | Your Amplitude API key. |
| `context` | `Context` | Yes | n/a | The Android application context. |
| `deviceId` | `String?` | Yes | n/a | Identifier for the device running your application. Pass `null` to suppress capture when a device ID is not yet available. |
| `sessionId` | `Long` | Yes | n/a | Identifier for the user's current session, in milliseconds since epoch (Unix timestamp). To use a string session ID instead, pass `-1` and call `setCustomSessionId` after initialization. Refer to [Custom session IDs](#custom-session-ids). |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `optOut` | `Boolean` | No | `false` | Sets permission to collect replays. A value of `true` prevents Amplitude from collecting session replays. |
| `logger` | `Logger` | No | `LogcatLogger` | Sets a custom logger to emit log messages to a destination. Set to `null` to disable logging. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. |
| `serverZone` | `ServerZone` | No | `ServerZone.US` | `ServerZone.EU` or `ServerZone.US`. Set this to EU for Amplitude projects created in the EU data center. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views are masked. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. See [Mask level](#mask-level). |
| `serverUrl` | `String?` | No | `null` | _Advanced._ Full URL that Session Replay uploads data to, for example your [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests). Overrides `serverZone`. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | _Advanced._ Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | _Advanced._ Local storage limit, in MB. |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when Session Replay initializes. |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Custom session IDs

Session Replay for Android version 0.26.4 and later supports string session IDs, for example UUIDs, through the `setCustomSessionId` method. Use a custom session ID if your project defines sessions with a custom event property instead of a timestamp-based `session_id`.

The constructor accepts only a numeric `sessionId`. To use a string value, pass `-1` as the `sessionId`, then call `setCustomSessionId`. Session Replay doesn't capture until you set a valid session ID.

```kotlin
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    context = applicationContext,
    deviceId = "device-id",
    sessionId = -1,
    sampleRate = 1.0,
)

// Set a string session ID instead of the numeric sessionId
sessionReplay.setCustomSessionId("ef197fc7-a46f-4e6c-a77f-8d90c17065c0")

// Whenever your custom session changes
sessionReplay.setCustomSessionId(ThirdPartyAnalytics.getCustomSessionId())
```

The numeric `sessionId` and the custom session ID are two views of the same underlying value, which the SDK stores as a string:

- Calling `setSessionId` replaces the current custom session ID with the numeric value. When you use custom session IDs, call `setCustomSessionId` instead of `setSessionId` whenever the session changes.
- When the stored value isn't numeric, `getSessionId` returns `-1`. Call `getCustomSessionId` to read the current value.
- Setting a different value ends the current replay and starts a new one.

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

- The value can't contain `/`. Session Replay uses `/` as a delimiter in the session replay ID, which has the format `<deviceId>/<sessionId>`.
- The value can only contain the characters `a-z A-Z 0-9 _ - . | @ : =`.
- The value must match the session-defining property you send on events to Amplitude. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

### Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

> **Note:** Remote configuration and testing
>
> With `enableRemoteConfig` set to `true`, settings you define in Amplitude take precedence over settings you define locally in the SDK. For this reason, while testing your application, you should **disable** remote configuration to ensure you can set `sampleRate` to `1`, and ensure you capture test sessions.

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

Session Replay provides an opt-out configuration option. Pass `optOut = true` during initialization to prevent Amplitude from collecting session replays. For example:

```kotlin
// Pass a boolean value to indicate a users opt-out status
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    optOut = true,
    /* other session replay options */
)
```

Call `setOptOut` at runtime to pause or resume capture without restarting the SDK:

```kotlin
// Pause capture
sessionReplay.setOptOut(true)

// Resume capture
sessionReplay.setOptOut(false)

// Check the current opt-out state
val isOptedOut = sessionReplay.getOptOut()
```

### 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:

```kotlin
// Set serverZone to EU
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    serverZone = ServerZone.EU,
    /* other session replay options */
)
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```kotlin
// This configuration samples 1% of all sessions
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    sampleRate = 0.01,
    /* other session replay options */
)
```

### Disable replay collection

After Session Replay starts, it runs in your app until either:

- The user leaves your app.
- You call `sessionReplay.stop()`.
- You call `sessionReplay.shutdown()` to tear down the instance.

Call `sessionReplay.stop()` before a user navigates to a restricted area of your app to pause replay collection while the user is in that area. Call `sessionReplay.start()` to resume when they return. Both methods act on the same instance.

To tear down Session Replay completely, call `sessionReplay.shutdown()`, then create a new instance to start again.

To capture only specific screens, initialize Session Replay with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    context = applicationContext,
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    autoStart = false,
)

// Start capture when the user enters a screen you want to record
sessionReplay.start()

// Stop capture when the user leaves that screen
sessionReplay.stop()
```

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, then add the flag to your initialization logic:

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
import com.example.ThirdPartyAnalytics

val sessionReplay = SessionReplay(
    apiKey = "AMPLITUDE_API_KEY",
    deviceId = "device-id",
    sessionId = System.currentTimeMillis(),
    sampleRate = 1.0,
    /* other session replay options */
)
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

Starting in version 0.32.0, Session Replay applies the browser privacy policy to web content inside captured WebViews. Elements within the WebView are masked or blocked according to the same rules that govern browser-based Session Replay, so sensitive fields such as password inputs remain masked even when the WebView is unmasked for capture.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out of tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

The SDK stores replay data locally. It retries transient upload failures, subject to retry and storage limits.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

## Troubleshooting

For more information about individual statuses and errors, see the [Session Replay Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).                                                                                    |

### 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 the `[Amplitude] End Session` occurs, but before the Android SDK and Session Replay plugin can process it. When the user uses the app 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 don't appear in Amplitude

Session replays may not appear in Amplitude due to:

- Lack of connectivity
- The app process ends or you shut down the SDK before pending replay data uploads.
- Sampling

#### Lack of connectivity

Ensure your app has access to the internet then try again.

#### Sampling

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

### Session Replay processing errors

In general, replays should be available within minutes of ingestion. Delays or errors may be the result of one or more of the following:

- Mismatching API keys or Device IDs. This can happen if Session Replay and standard event instrumentation use different API keys or Device IDs.
- Session Replay references the wrong project.
- Short sessions. If a users bounces within a few seconds of initialization, the SDK may not have time to upload replay data.
- Page instrumentation. If Session Replay isn't implemented on all pages a user visits, their session may not capture properly.
- Replays older than the set [retention period](#retention-period) (defaults to 90 days).

### Report an Issue

If you encounter any issues with Session Replay that aren't covered in the troubleshooting guide above, please report them on our [GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-Android).

When creating an issue, please include:

- A clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- SDK version you're using
- Any relevant error messages or logs

================================================================================
# Session Replay Android Middleware
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-android-middleware
Updated: 2026-11-04
================================================================================

# Session Replay Android Middleware

> **Alpha:** Early access SDK
>
> As an Alpha release, this SDK may contain bugs and cause crashes. Before you enable in production, thoroughly test your app in a controlled environment. For more information about best practices for developer preview SDKs, see [SDK Maintenance and Support](https://amplitude.com/docs/sdks/sdk-maintenance-and-support#sdk-major-version-life-cycle).

The Session Replay Android middleware adds Session Replay to an app that already uses the [(maintenance) Amplitude SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk). It attaches to your existing SDK instance through [Android SDK middleware](https://amplitude.com/docs/sdks/sdk-middleware) and captures replays alongside the events you track.

If your app already uses the [(latest) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk/get-started), use the [Session Replay Android SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-android-plugin).

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-android-standalone).

> **Note:** Session Replay and performance
>
> Amplitude built Session Replay to minimize impact on the performance of the Android apps in which it's installed by:
>
> - Asynchronously capturing and processing replay data, to avoid blocking the main user interface thread. The main thread must analyze the view hierarchy, but snapshot capture scheduling and extra processing offloads to the background.
> - Using batching and lightweight compression to reduce the number of network connections and bandwidth.
> - Optimizing view hierarchy processing. Contact Amplitude if you experience issues with hierarchy processing.

## Prerequisites

The Session Replay Middleware requires that:

1. Your application targets Android.
2. You use version `2.40.1` or higher of the [(maintenance) Amplitude Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-sdk).
3. You can provide a device ID to the SDK.

### Supported Android versions

Session replay supports down to Android 5.0 with a minimum SDK of 21 `minSdk = 21`. This should support over 99.6% of global Android devices according to Google's distribution data in Android Studio.

## Quickstart

Add the [latest version](https://central.sonatype.com/artifact/com.amplitude/middleware-session-replay-android/versions) of the Session Replay middleware to your project dependencies.

```kotlin
// Install latest version from Maven Central
implementation("com.amplitude:middleware-session-replay-android:0.26.1")
// You will also need the (maintenance) Amplitude Analytics SDK if it's not already installed
implementation("com.amplitude:android-sdk:[2.40.1,3.0.0)")
```

Configure your application code.

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Initialize (maintenance) Amplitude Analytics SDK instance
val amplitude = Amplitude.getInstance()
    .initialize(this, "AMPLITUDE_API_KEY")
    // Replay events will be flushed on close as well
    // If setFlushEventsOnClose(false) you must call flush() manually
    .setFlushEventsOnClose(true)

// Create Session Replay Middleware
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0)

// Add session replay middleware
// Recording will be handled automatically
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Track events
amplitude.logEvent("Setup (maintenance) Amplitude Android SDK with session replay!")

// Send replay events to the server
amplitude.uploadEvents()

// You can also call flush() on the middleware directly to only send replay events
// sessionReplayMiddleware.flush()

// Always flush before app exit (onPause)
// override fun Activity.onPause() { sessionReplayMiddleware.flush() }
```

## Configuration

Pass the following options when you initialize the Session Replay middleware:

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `amplitude` | `AmplitudeClient` | Yes | n/a | The maintenance Amplitude SDK client instance to attach to. |
| `sampleRate` | `Number` | No | `0.0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, which selects 40% of sessions over a large number of sessions. |
| `enableRemoteConfig` | `Boolean` | No | `true` | Enables or disables remote configuration for this instance of Session Replay. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig()` | Privacy settings that control which views Session Replay masks. Set the mask level with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. Refer to [Mask level](#mask-level). |
| `autoStart` | `Boolean` | No | `true` | Starts screen capture automatically when the middleware initializes. |
| `bandwidthLimitBytes` | `Int?` | No | `null` | Advanced. Daily upload limit, in bytes, on metered (for example, cellular) connections. |
| `storageLimitMB` | `Int?` | No | `null` | Advanced. Local storage limit, in MB. |
| `serverUrl` | `String?` | No | `null` | Advanced. Full upload URL for a [proxy](https://amplitude.com/docs/session-replay/proxy-replay-requests). Overrides the server zone. Set it with `SessionReplayMiddleware.Builder` (version 0.33.0 or later). |
| `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Maximum number of logs per session. |
| `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Maximum length of a log message. |

### Mask on-screen data

The Session Replay SDK offers four ways to mask user input, text, and other view components.

#### Mask level

Session Replay for Android supports three levels of masking, set through the `privacyConfig` option with `PrivacyConfig(maskLevel = MaskLevel.MEDIUM)`. The default level is `medium`.

Use this option in the Session Replay configuration.

| Mask level | Description |
| --- | --- |
| `light` | Masks password, email, and phone number input fields. In SDK `0.26.2` and later, `light` also masks any field with sensitive autofill hints (credit card number, expiration, and security code; name; username; postal address and code); autofill-hint detection requires Android 8.0 (API 26) or higher. Earlier versions, including the `middleware-session-replay-android` artifact, mask only the input-field types above. |
| `medium` (default) | Everything in `light`, plus all editable text fields (`EditText`). |
| `conservative` | Everything in `medium`, plus all text views (`TextView`). |

#### Privacy tags in layout XML

Use this option in your application's layout XML.

| View | Description |
| --- | --- |
| `<EditText>` | Session Replay masks all text input fields by default. When a users enters text into an input field, Session Replay captures asterisks in place of text. To _unmask_ a text input, add the tag `amp-unmask`. For example: `<EditText android:tag="amp-unmask" android:text="Unmask this">`. |
| `<TextView>` | To mask text within non-input elements, add the tag `amp-mask`. For example, `<TextView android:tag="amp-mask" android:text="Mask this"/>`. When masked, Session Replay captures masked text as a series of asterisks. |
| non-text elements | To block a non-text element, add the tag `amp-block`. For example, `<ImageView android:tag="amp-block"/>`. Session Replay replaces blocked elements with a placeholder of the same dimensions. |
| `<WebView>` | To unmask a web view, add the `amp-unmask` tag. For example, `<WebView android:tag="amp-unmask"/>`. |

#### Privacy methods on the Session Replay SDK

Import the `SessionReplay` class, then call one of the methods below from your application's code.

```kotlin
import com.amplitude.android.sessionreplay.SessionReplay
```

| Method | Description |
| --- | --- |
| `unmask(view: View)` | To unmask a view manually, call `SessionReplay.unmask(view)` where `view` is a reference to any view that is masked. |
| `mask(view: View)` | To mask text within non-input views, call `SessionReplay.mask(view)` where `view` is a reference to the any view you want to mask. When masked, Session Replay captures masked text as a series of asterisks. |
| `block(view: View)` | To block a non-text view, call `SessionReplay.block(view)` where `view` is a reference to the View you want to block. Session Replay replaces blocked views with a placeholder of the same dimensions. |

#### Privacy modifiers in Jetpack Compose

For composables, use the privacy modifiers instead of layout XML tags or the `SessionReplay` methods. These modifiers require version `0.21.0` or higher of the Session Replay Android SDK or plugin.

Import the modifier you need from `com.amplitude.android.sessionreplay.compose`, then add it to the composable's modifier chain.

```kotlin
import com.amplitude.android.sessionreplay.compose.ampMask
import com.amplitude.android.sessionreplay.compose.ampUnmask
import com.amplitude.android.sessionreplay.compose.ampBlock
```

| Modifier | Description |
| --- | --- |
| `Modifier.ampMask()` | Masks text that Session Replay captures by default, such as the contents of a `Text` composable. Session Replay captures masked text as a series of asterisks. |
| `Modifier.ampUnmask()` | Unmasks a composable that Session Replay masks by default, such as a `TextField`. |
| `Modifier.ampBlock()` | Blocks a composable. Session Replay replaces blocked composables with a placeholder of the same dimensions and doesn't capture their contents. |

```kotlin
// Mask text that Session Replay captures by default
Text(
    text = "Account number: 123456789",
    modifier = Modifier.ampMask(),
)

// Unmask an input field that Session Replay masks by default
TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.ampUnmask(),
)

// Block a composable and everything it contains
Box(modifier = Modifier.ampBlock()) {
    Text("Session Replay doesn't capture this content")
}
```

A privacy modifier applies to the composable you add it to and to everything nested inside it. When a nested composable has its own privacy modifier, that modifier takes precedence for that composable and its descendants.

### User opt-out

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

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Set optOut on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, "AMPLITUDE_API_KEY")
        .setOptOut(true)

amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))
```

### 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:

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Set serverZone on the Amplitude SDK
val amplitude = Amplitude.getInstance()
        .initialize(this, "AMPLITUDE_API_KEY")
        .setServerZone(AmplitudeServerZone.EU)

amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, /* session replay options */))
```

### Send replay uploads to a proxy

To route replay uploads through your own server, set `serverUrl` with `SessionReplayMiddleware.Builder`, available in version 0.33.0 or later. For proxy requirements, go to [Proxy Session Replay requests](https://amplitude.com/docs/session-replay/proxy-replay-requests).

```kotlin
import com.amplitude.api.SessionReplayMiddleware

val sessionReplayMiddleware = SessionReplayMiddleware.Builder(amplitude)
    .sampleRate(1.0)
    .serverUrl("https://replay.yourdomain.com/sessions/v2/track")
    .build()
amplitude.addEventMiddleware(sessionReplayMiddleware)
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's `sampleRate` configuration option to set the proportion of sessions to capture.

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

```kotlin
// This configuration samples 1% of all sessions
amplitude.addEventMiddleware(SessionReplayMiddleware(amplitude, sampleRate = 0.01))
```

### Disable replay collection

After it starts, Session Replay runs in your app until either:

- The user leaves your app.
- You call `sessionReplayMiddleware.stop()`.

Call `sessionReplayMiddleware.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

> **Note:** Keep a reference
>
> Keep a reference to the `SessionReplayMiddleware` instance: `val sessionReplayMiddleware = SessionReplayMiddleware(/* session replay options */)`.

Call `sessionReplayMiddleware.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the middleware with `autoStart = false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```kotlin
// Add the middleware without starting capture
val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 1.0, autoStart = false)
amplitude.addEventMiddleware(sessionReplayMiddleware)

// Start capture when the user enters a screen you want to record
sessionReplayMiddleware.start()

// Stop capture when the user leaves that screen
sessionReplayMiddleware.stop()
```

You can also use a feature flag product like Amplitude Experiment to enable or disable 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:

```kotlin
import com.amplitude.api.Amplitude
import com.amplitude.api.SessionReplayMiddleware

// Your existing initialization logic with Android SDK
val amplitude = Amplitude.getInstance().initialize(this, "AMPLITUDE_API_KEY")

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Middleware
  val sessionReplayMiddleware = SessionReplayMiddleware(amplitude, sampleRate = 0.5)
  amplitude.addEventMiddleware(sessionReplayMiddleware)
}
```

### WebView and MapView support (Beta)

By default, Session Replay blocks web views and map views in a capture. To enable capture of these components, use the settings described in [Mask on-screen data](#mask-on-screen-data).

Web view session replay injects JavaScript into the rendered page. To enable this, the SDK sets `javaScriptEnabled` to `true` on the unmasked web view.

### Log Recording

> **Note:** Availability
>
> Log recording is available in Session Replay Android `0.22.0` and later.

Session Replay supports recording logs in Android applications. To enable log recording, send log messages through the `recordLog(level, message, timestamp)` API and configure the limits through `recordLogOptions` parameter while initializing Session Replay.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import com.amplitude.android.sessionreplay.config.RecordLogOptions

val sessionReplayPlugin = SessionReplayPlugin(
    recordLogOptions = RecordLogOptions(
        logCountThreshold = 2000,
        maxMessageLength = 4000
    )
)
amplitude.add(sessionReplayPlugin)

sessionReplayPlugin.recordLog(RecordLogLevel.Error, "This is an error log")

// You can also create custom log levels
sessionReplayPlugin.recordLog(RecordLogLevel("debug"), "This is a debug log")
```

Session Replay supports predefined log levels (`Error`, `Warn`, `Log`) and custom log levels. Create custom log levels by passing any string value to `RecordLogLevel(...)`.

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

#### Timber

If you use `Timber`, you can integrate it with a custom tree.

```kotlin
import com.amplitude.android.plugins.SessionReplayPlugin
import com.amplitude.android.sessionreplay.config.RecordLogLevel
import timber.log.Timber

class AmplitudeLogRecordTree(private val plugin: SessionReplayPlugin) : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val recordLevel = when (priority) {
            android.util.Log.ERROR -> RecordLogLevel.Error
            android.util.Log.WARN -> RecordLogLevel.Warn
            android.util.Log.INFO -> RecordLogLevel.Log
            android.util.Log.DEBUG -> RecordLogLevel("debug")
            android.util.Log.VERBOSE -> RecordLogLevel("verbose")
            else -> return
        }
        plugin.recordLog(recordLevel, message)
    }
}

val sessionReplayPlugin = SessionReplayPlugin()
amplitude.add(sessionReplayPlugin)

Timber.plant(AmplitudeLogRecordTree(sessionReplayPlugin))
```

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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

If a user opts out of tracking in your app, use the `optOut` configuration option to disable replay collection for that user.

The SDK stores replay data locally. It retries transient upload failures, subject to retry and storage limits.

Amplitude recommends setting `amplitude.setFlushEventsOnClose(true)` in the Amplitude SDK configuration (the default) to send session data to the server on each app exit.

## Jetpack Compose Support (Alpha)

Session Replay supports Jetpack Compose for Android applications. This feature is currently in Alpha. To use Jetpack Compose with Session Replay, ensure you use version `0.20.4` or higher of the Session Replay Android SDK or plugin.

To control what Session Replay captures in a composable, use the [privacy modifiers in Jetpack Compose](#privacy-modifiers-in-jetpack-compose). Masking support for Compose requires `0.21.0` or higher.

## Known limitations

Keep the following limitations in mind as you implement Session Replay:

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

  - You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  - A known user begins on one app, and then switch to another.
  - Amplitude captures both sessions.
  - The replay for each session is available for view in the corresponding host project.
- The User Sessions chart doesn't show session replays if your organization uses a custom session definition.
- Session Replay can't capture the following Android views:

  - Canvas Views

================================================================================
# Session Replay React Native SDK Plugin
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin
Updated: 2026-11-04
================================================================================

# Session Replay React Native SDK Plugin

- **Package:** `@amplitude/plugin-session-replay-react-native` ([npm](https://www.npmjs.com/package/@amplitude/plugin-session-replay-react-native))
- **Latest version:** 0.5.12
- **Package size:** 0.9 kB gzip

This article covers how to install Session Replay using the [React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk) plugin. If your application uses the Amplitude React Native SDK, use this option.

If you instrument Session Replay without the Amplitude Analytics SDK, go to the [Session Replay React Native Standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk).

## Quickstart

#### npm

```bash
npm install @amplitude/plugin-session-replay-react-native --save
```

#### yarn

```bash
yarn add @amplitude/plugin-session-replay-react-native
```

Configure your application code.

```js
import { SessionReplayPlugin, MaskLevel } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // default 0
    autoStart: true, // default true
    maskLevel: MaskLevel.Medium, // default Medium
};
await init('AMPLITUDE_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;
```

> **Info:** Using Experiment and Session Replay together
>
> Register Session Replay after Analytics initialization. If your app also uses `@amplitude/plugin-experiment-react-native`, you can register the Experiment plugin before or after Analytics initialization.

## Configuration

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Session Replay selects 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. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings). |
| `logLevel` | `LogLevel` | No | `LogLevel.Warn` | Sets the log level for the Session Replay plugin. |
| `autoStart` | `boolean` | No | `true` | Controls whether Session Replay starts automatically when initialized. If set to `false`, manually call the `start()` method to begin capture. |
| `maskLevel` | `MaskLevel` | No | `Medium` | Level of masking applied to sensitive content. Options: `Light`, `Medium`, `Conservative`. Configure this setting to control automatic masking behavior, or use remote configuration through the Session Replay settings page. |

### Mask onscreen data

Session Replay lets you mask or obfuscate areas of your application that may contain sensitive data or PII. Masking happens at the view level. To mask a view, add the `AmpMaskView` tag with the `amp-mask` mask property around the section you're masking.

```js
import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";

// ...

<AmpMaskView mask="amp-mask">
  <Text
    style={[
      styles.sectionTitle,
      {
        color: isDarkMode ? Colors.white : Colors.black,
      },
    ]}
  >
    {title}
  </Text>
</AmpMaskView>;
```

`AmpMaskView` is a regular React Native layout node, so it takes part in layout exactly like a `View` and doesn't make itself transparent to layout. When you wrap existing content, apply the sizing and flex styles that the content relies on to the `AmpMaskView` itself, such as `flex: 1`, an explicit `width` and `height`, or `alignItems`. Without those styles, the wrapper can collapse or resize the region you wrapped.

To unmask a view later, change the mask property to `amp-unmask`.

```js
import { AmpMaskView } from "@amplitude/plugin-session-replay-react-native";

// ...

<AmpMaskView mask="amp-unmask">
  <Text
    style={[
      styles.sectionTitle,
      {
        color: isDarkMode ? Colors.white : Colors.black,
      },
    ]}
  >
    {title}
  </Text>
</AmpMaskView>;
```

To replace a view with an empty placeholder of the same dimensions, set the mask property to `amp-block`.

#### Platform differences in masking

Android and iOS resolve `AmpMaskView` with different native Session Replay libraries, so identical markup can behave differently on each platform. Test your masking on both platforms before you release.

| Behavior | Android | iOS |
| --- | --- | --- |
| Marker resolution | The nearest explicit mask marker wins. | A masked parent wins over any marker nested inside it. |
| `amp-unmask` nested inside a masked region | The nested subtree becomes visible again in the replay. | The nested subtree stays masked. iOS doesn't support nested unmasking. |
| Where `amp-unmask` takes effect | Anywhere, including inside a region that `amp-mask` covers. | Only outside masked regions, such as on content that the mask level masks. |
| Masked text in the replay | Asterisks that preserve the length of the original text. | No image and no text. The region renders as a flat gray fill. |
| `amp-block` in the replay | Session Replay sends no bitmap for the view, and the player renders a placeholder. | The region renders as a flat gray fill, the same as `amp-mask`. |

Session Replay applies these representations on the device when it captures each frame, so the uploaded replay data holds the masked representation instead of the original text or pixels. The player can't restore masked content later.

To keep a region visible on both platforms, place its `amp-unmask` wrapper outside every `amp-mask` and `amp-block` region rather than nesting it inside one.

### User opt-out

The Session Replay plugin follows the [React Native SDK's `optOut` setting](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk#opt-users-out-of-tracking), and doesn't support user opt-outs on its own.

### Start and stop recording

The Session Replay plugin provides `start()` and `stop()` methods to start and stop recording sessions. Call these methods to control the recording of specific pages or features in your application.

```js
import { SessionReplayPlugin } from "@amplitude/plugin-session-replay-react-native";

// ...

await init("AMPLITUDE_API_KEY").promise;
const sessionReplayPlugin = new SessionReplayPlugin();
await add(sessionReplayPlugin).promise;

// Stop recording
await sessionReplayPlugin.stop();

// Resume recording
await sessionReplayPlugin.start();
```

To initialize the plugin without automatically starting capture, set the `autoStart` configuration option to `false`:

```js
import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true,
    sampleRate: 1,
    autoStart: false, // Don't start capturing automatically
};
await init('AMPLITUDE_API_KEY').promise;
const sessionReplayPlugin = new SessionReplayPlugin(config);
await add(sessionReplayPlugin).promise;

// Later, when you want to begin capture
await sessionReplayPlugin.start();
```

### 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
import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // default 0
    serverZone: "EU" // [tl! ~~]
};
await init('AMPLITUDE_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;
```

### Sampling rate

By default, Session Replay captures 0% of sessions for replay. If you enable Remote Configuration, 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
import { SessionReplayPlugin } from '@amplitude/plugin-session-replay-react-native';

// ...

const config: SessionReplayConfig = {
    enableRemoteConfig: true, // default true
    sampleRate: 1, // [tl! ~~]
};
await init('AMPLITUDE_API_KEY').promise;
await add(new SessionReplayPlugin(config)).promise;
```

To set the `sampleRate`, consider the monthly quota on your Session Replay plan. For example, if your monthly quota is 2,500,000 sessions and you average 3,000,000 monthly sessions, your quota is 83% of your average sessions. In this case, to ensure sampling lasts through the month, set `sampleRate` to `.83` or lower.

Note the following as you consider your sample rate:

- When you reach your monthly session quota, Amplitude stops capturing sessions for replay.
- Session quotas reset on the first of every month.
- Use sample rate to distribute your session quota across a month, rather than using your full quota at the beginning of the month.
- To find the best sample rate, Amplitude recommends that you start low, for example `.01`. If this value doesn't capture enough replays, raise the rate over a few days. For ways to monitor the number of session replays captured, refer to [View the number of captured sessions](https://amplitude.com/docs/session-replay).

Session Replay supports remote sampling rate settings. This lets users in your organization configure or update the sampling rate of your project after implementation, without a code change. If there's a conflict, Session Replay defaults to the remote setting. For more information, refer to [Account Settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

## Troubleshooting

### Android crashes with null pointer exception

If your Android app crashes with a `NullPointerException` related to the `serverZone` parameter when using custom server URLs, ensure you're using the latest version of the Session Replay React Native plugin. Earlier versions required you to explicitly set the `serverZone` parameter when using custom `serverUrl` configurations.

The error typically appears as:

```text
java.lang.NullPointerException: Parameter specified as non-null is null: method com.amplitude.pluginsessionreplayreactnative.PluginSessionReplayReactNativeModule.setup, parameter serverZone
```

**Solution**: Update to the latest version of `@amplitude/plugin-session-replay-react-native`, where the `serverZone` parameter is optional and defaults to `US` if not specified.

## Track web views (beta)

By default, Session Replay blocks web views, and doesn't track them. If you want to track web views in your application, wrap the view in the `AmpMaskView` tag, and apply the `amp-unmask` mask property.

```js
<AmpMaskView mask="amp-unmask" style={{ flex: 1 }}>
  <WebView source={{ uri: "https://reactnative.dev/" }} style={{ flex: 1 }} />
</AmpMaskView>
```

## 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 Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not the raw replay data. Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. This event includes the `[Amplitude] Session Replay ID` property, which provides information about the sessions collected for replay for the user.

```json
{
 "amplitude_id": 123456789,
 "app": 12345,
 "event_time": "2020-02-15 01:00:00.123456",
 "event_type": "first_event",
 "server_upload_time": "2020-02-18 01:00:00.234567",
 "device_id": "your device id",
 "user_properties": { ... }
 "event_properties": {
 "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
 }
 "session_id": 1699922971244,
}
```

### Data deletion

Session Replay uses Amplitude's [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy/) to handle deletion requests. Successful deletion requests remove all session replays for the specified user.

When you delete the Amplitude project that uses Session Replay, Amplitude deletes that replay data.

### Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) available in the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

================================================================================
# Session Replay React Native Segment Integration
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-segment-integration
Updated: 2026-09-09
================================================================================

# Session Replay React Native Segment Integration

This article covers how to install Session Replay using the Session Replay React Native Segment plugin. If your React Native app already uses Segment's Analytics React Native library and Amplitude (Actions) destination, use this option.

If you instrument your app with an [Amplitude React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk), use the [Session Replay React Native SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin).

If you use Segment with other options, use the [standalone implementation](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk).

> **Tip:** Report issues
>
> To report issues with Session Replay for React Native, go to the [Amplitude-TypeScript GitHub repository](https://github.com/amplitude/Amplitude-TypeScript).

> **Warning:** Amplitude Session Plugin required
>
> This plugin requires the `@segment/analytics-react-native-plugin-amplitude-session` plugin to extract session IDs from Amplitude integration data. Add this plugin to your Segment client before you add the session replay plugin.

> **Note:** API key matching
>
> The Amplitude API key in the session replay plugin configuration must match the API key in your Segment Amplitude (Actions) destination.

## Before you begin

Use the latest version of the Session Replay React Native Segment Plugin with `@amplitude/session-replay-react-native` version `1.0.1` or later. Version `1.0.1` is the first generally available release of the standalone SDK.

The Session Replay React Native Segment Plugin requires that:

1. You build your application with React Native.
2. You use Segment's Analytics React Native library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's [Amplitude Session Plugin](https://segment.com/docs/connections/sources/catalog/libraries/mobile/react-native/destination-plugins/amplitude-react-native/) to extract session IDs.

## Quickstart

Install the plugin and its dependencies:

#### npm

```bash
npm install @amplitude/segment-session-replay-plugin-react-native
npm install @amplitude/session-replay-react-native @segment/analytics-react-native
```

#### yarn

```bash
yarn add @amplitude/segment-session-replay-plugin-react-native
yarn add @amplitude/session-replay-react-native @segment/analytics-react-native
```

Configure your application code:

```js
import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';
import { createClient } from '@segment/analytics-react-native';
import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude-session';

// Initialize Segment client
const segmentClient = createClient({
  writeKey: 'YOUR_SEGMENT_WRITE_KEY',
});

// Configure session replay plugin
const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  deviceId: 'YOUR_DEVICE_ID'
};

// Add the Amplitude session plugin first (required for session ID extraction)
await segmentClient.add({ plugin: new AmplitudeSessionPlugin() });

// Add the session replay plugin to Segment
await segmentClient.add({ plugin: createSegmentSessionReplayPlugin(sessionReplayConfig) });
```

## Configuration

The plugin accepts a `SessionReplayConfig` object with the following options:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | Yes | - | Your Amplitude API key. This must match the API key for your Segment Amplitude destination. |
| `deviceId` | `string` | No | - | The device ID for session replay. If not provided, the plugin extracts it from the Segment event context. |
| `sampleRate` | `number` | No | `0` | Controls how many sessions Amplitude selects for replay collection. Use a decimal between 0 and 1, for example `0.4`, to represent the fraction of sessions Amplitude randomly selects for replay collection. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings). |
| `logLevel` | `LogLevel` | No | `LogLevel.Warn` | Sets the log level for the Session Replay plugin. |
| `autoStart` | `boolean` | No | `true` | Controls whether Session Replay starts automatically after initialization. If set to `false`, manually call the `start()` method to begin capture. |

## How it works

The Segment Session Replay Plugin automatically:

1. Initializes Session Replay: sets up Amplitude Session Replay with your configuration when you add the plugin to Segment.
2. Syncs session data: updates the session ID and device ID for each Segment event by extracting them from event properties or Amplitude integration data.
3. Enriches events: adds session replay properties to `track` and `screen` events before sending them to Segment.
4. Manages lifecycle: handles start and stop operations for session replay based on the plugin lifecycle.

### Event processing

The plugin processes the following Segment event types:

- `TrackEvent`: adds session replay properties to track events.
- `ScreenEvent`: adds session replay properties to screen events.

For these events, the plugin:

- Extracts the session ID from event properties or Amplitude integration data.
- Extracts the device ID from the event context or anonymous ID.
- Adds session replay properties to the event before sending it to Segment.

### Session ID extraction

The plugin extracts session IDs in the following order of priority:

1. From Amplitude integration data: `event.integrations['Actions Amplitude'].session_id`.
2. From event properties: `event.properties.session_id`.
3. Defaults to `-1` if Amplitude finds no session ID.

### Device ID extraction

The plugin extracts device IDs in the following order of priority:

1. From event context: `event.context.device.id`.
2. From anonymous ID: `event.anonymousId`.
3. Defaults to `null` if Amplitude finds no device ID.

## Advanced topics

This section provides examples for more advanced use cases.

### Manual control

Manually control the session replay plugin after initialization:

```js
import { createSegmentSessionReplayPlugin } from '@amplitude/segment-session-replay-plugin-react-native';

// Create the plugin
const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);

// Add to Segment
await segmentClient.add(sessionReplayPlugin);

// Later, manually control recording
await sessionReplayPlugin.start();
await sessionReplayPlugin.stop();
```

### Custom configuration

For more advanced configurations, pass additional session replay options:

```js
const sessionReplayConfig = {
  apiKey: 'YOUR_AMPLITUDE_API_KEY',
  sampleRate: 0.1, // Sample 10% of sessions
  enableRemoteConfig: true,
  logLevel: 4, // Debug level
  autoStart: false, // Don't start automatically
};

const sessionReplayPlugin = createSegmentSessionReplayPlugin(sessionReplayConfig);
```

## Troubleshooting

### Session replay properties not added

If the plugin doesn't add session replay properties to your events:

1. Verify that the Amplitude Session Plugin appears before the Session Replay Plugin.
2. Check that your Segment events are of type `track` or `screen`.
3. Confirm that the session replay plugin initializes.

### Session ID not found

If the plugin can't extract session IDs:

1. Verify that you configured the Amplitude Session Plugin correctly.
2. Check that you configured the Segment Amplitude destination correctly.
3. Confirm that events include the required Amplitude integration data.

### Device ID issues

If device ID extraction fails:

1. Check that your Segment events include device information in the context.
2. Verify that Segment sets the anonymous ID.
3. Consider manually setting the device ID in the plugin configuration.

For additional troubleshooting, go to the [Session Replay React Native SDK Plugin troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin).

================================================================================
# Session Replay React Native Standalone SDK
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-standalone-sdk
Updated: 2026-11-04
================================================================================

# Session Replay React Native Standalone SDK

- **Package:** `@amplitude/session-replay-react-native` ([npm](https://www.npmjs.com/package/@amplitude/session-replay-react-native))
- **Latest version:** 1.1.0
- **Package size:** 1.4 kB gzip

The Session Replay React Native standalone SDK records mobile sessions and uploads them to Amplitude without the Amplitude Analytics SDK. Use it when another analytics provider already instruments your app, or when you manage Amplitude `deviceId` and `sessionId` yourself. If your app already uses the Amplitude React Native Analytics SDK, install the [Session Replay React Native SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin) instead.

You need an Amplitude API key. After you install the package, rebuild the native app. Expo Go doesn't include this native module, so use a development build or a prebuild client.

For changelog details, go to the [package change log](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/session-replay-react-native/CHANGELOG.md) on GitHub.

## Install the SDK

#### npm

```bash
npm install @amplitude/session-replay-react-native --save
```

#### yarn

```bash
yarn add @amplitude/session-replay-react-native
```

## Quickstart

`init()` configures the SDK and doesn't start capture. Call `start()` after you pass matching `deviceId` and `sessionId` values.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
  privacyConfig: {
    maskLevel: "medium",
  },
});

await start();
```

## Correlate replays with analytics events

Session Replay matches a replay to analytics events when the standalone SDK and your analytics SDK send the same `deviceId` and `sessionId`. Pass those values into `init()`, then call `setDeviceId()` and `setSessionId()` whenever either identifier changes.

```js
import {
  setDeviceId,
  setSessionId,
} from "@amplitude/session-replay-react-native";

await setDeviceId("new-device-id");
await setSessionId(Date.now());
```

The standalone SDK doesn't manage sessions for you. Your app or third-party analytics integration must keep both identifiers in sync.

## Configuration

Pass this configuration to `init()`.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `string` | Yes | - | Your Amplitude API key. |
| `deviceId` | `string | null` | No | `null` | Device identifier that matches the device ID on your analytics events. |
| `sessionId` | `number | string` | No | `-1` | Session identifier that matches the session ID on your analytics events. Accepts a number (milliseconds since epoch), or an opaque string such as a UUID. |
| `sampleRate` | `number` | No | `0` | Fraction of sessions to capture, as a decimal between `0` and `1`. For example, `0.4` selects 40% of sessions over a large sample. |
| `enableRemoteConfig` | `boolean` | No | `true` | Enables [remote configuration](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings). |
| `logLevel` | `LogLevel` | No | `LogLevel.Warn` | Sets the log level for the Session Replay SDK. Import `LogLevel` from `@amplitude/session-replay-react-native`, then pass `LogLevel.None`, `LogLevel.Error`, `LogLevel.Warn`, `LogLevel.Verbose`, or `LogLevel.Debug`. |
| `privacyConfig` | `{ maskLevel?: 'light' | 'medium' | 'conservative' }` | No | `{ maskLevel: 'medium' }` | Privacy options. Set `maskLevel` to `'light'`, `'medium'`, or `'conservative'`. |
| `optOut` | `boolean` | No | `false` | Set to `true` to skip session replay collection at initialization. |
| `serverZone` | `'US' | 'EU'` | No | `'US'` | Amplitude server zone. Set to `'EU'` for EU data residency. |

## Methods

### init

Configures the Session Replay SDK. Call this before any other Session Replay method. `init()` doesn't start capture.

```js
import { init } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
```

### start

Starts recording session replay. Call this after `init()`, and after a previous `stop()` when you want capture to resume.

```js
import { start } from "@amplitude/session-replay-react-native";

await start();
```

### stop

Stops recording session replay.

```js
import { stop } from "@amplitude/session-replay-react-native";

await stop();
```

### setSessionId

Updates the session identifier. Call this whenever the session ID on your analytics events changes. Accepts a number (milliseconds since epoch), or an opaque string such as a UUID.

```js
import { setSessionId } from "@amplitude/session-replay-react-native";

await setSessionId(Date.now()); // or `await setSessionId("<your-session-id>");`
```

### setDeviceId

Updates the device identifier. Call this whenever the device ID on your analytics events changes. Pass `null` to clear the device ID.

```js
import { setDeviceId } from "@amplitude/session-replay-react-native";

await setDeviceId("new-device-id");
await setDeviceId(null);
```

### getSessionId

Returns the current session identifier from the Session Replay SDK, or `null` if you haven't initialized the SDK.

```js
import { getSessionId } from "@amplitude/session-replay-react-native";

const sessionId = await getSessionId();
```

### setOptOut

Updates opt-out at runtime. Pass `true` to disable replay collection. Pass `false` to allow collection again, subject to sampling and whether you already called `start()`.

```js
import { setOptOut } from "@amplitude/session-replay-react-native";

await setOptOut(true);
await setOptOut(false);
```

### flush

Uploads pending session replay data immediately.

```js
import { flush } from "@amplitude/session-replay-react-native";

await flush();
```

### teardown

Shuts down native Session Replay and clears JavaScript lifecycle state. Call `init()` again before any other Session Replay method.

```js
import { init, start, teardown } from "@amplitude/session-replay-react-native";

await teardown();

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
await start();
```

## Mask onscreen data

Session Replay masks or obfuscates views that contain sensitive data or PII. Wrap the region with `AmpMaskView` and set `mask` to `amp-mask`, `amp-unmask`, or `amp-block`. `AmpMaskView` lays out like a normal `View`, so apply the same layout styles you use on a `View`.

```js
import { AmpMaskView } from "@amplitude/session-replay-react-native";

<AmpMaskView mask="amp-mask">
  <Text>{title}</Text>
</AmpMaskView>;
```

`AmpMaskView` is a regular React Native layout node, so it takes part in layout exactly like a `View` and doesn't make itself transparent to layout. When you wrap existing content, apply the sizing and flex styles that the content relies on to the `AmpMaskView` itself, such as `flex: 1`, an explicit `width` and `height`, or `alignItems`. Without those styles, the wrapper can collapse or resize the region you wrapped.

### Unmask views

To unmask a view that the global mask level otherwise masks, set `mask` to `amp-unmask`.

```js
import { AmpMaskView } from "@amplitude/session-replay-react-native";

<AmpMaskView mask="amp-unmask">
  <Text>{title}</Text>
</AmpMaskView>;
```

### Block views

To replace a view with an empty placeholder of the same dimensions, set `mask` to `amp-block`.

```js
import { AmpMaskView } from "@amplitude/session-replay-react-native";

<AmpMaskView mask="amp-block">
  <Text>Session Replay doesn't capture this content</Text>
</AmpMaskView>;
```

### Platform differences in masking

Android and iOS resolve `AmpMaskView` with different native Session Replay libraries, so identical markup can behave differently on each platform. Test your masking on both platforms before you release.

| Behavior | Android | iOS |
| --- | --- | --- |
| Marker resolution | The nearest explicit mask marker wins. | A masked parent wins over any marker nested inside it. |
| `amp-unmask` nested inside a masked region | The nested subtree becomes visible again in the replay. | The nested subtree stays masked. iOS doesn't support nested unmasking. |
| Where `amp-unmask` takes effect | Anywhere, including inside a region that `amp-mask` covers. | Only outside masked regions, such as on content that the mask level masks. |
| Masked text in the replay | Asterisks that preserve the length of the original text. | No image and no text. The region renders as a flat gray fill. |
| `amp-block` in the replay | Session Replay sends no bitmap for the view, and the player renders a placeholder. | The region renders as a flat gray fill, the same as `amp-mask`. |

Session Replay applies these representations on the device when it captures each frame, so the uploaded replay data holds the masked representation instead of the original text or pixels. The player can't restore masked content later.

To keep a region visible on both platforms, place its `amp-unmask` wrapper outside every `amp-mask` and `amp-block` region rather than nesting it inside one.

### Choose a masking level

Set `privacyConfig.maskLevel` in `init()`.

| Mask level | Description |
| --- | --- |
| `light` | Masks sensitive native text inputs, such as passwords. |
| `medium` (default) | Masks all React Native `TextInput` fields. |
| `conservative` | Masks all `TextInput` fields and standard React Native `Text` content. |

> **Note:** React Native masking limitations
>
> Session Replay doesn't automatically mask text that React Native renders outside standard native text views, including `react-native-svg`, Shopify Skia, and canvas-based renderers. Wrap those regions in `AmpMaskView`.
>
> On Android, `light` doesn't reliably identify credit-card fields. Use `medium` or `conservative`, or wrap the field in `AmpMaskView`, for cross-platform coverage.

Remote configuration on the Session Replay settings page takes precedence over the SDK. This SDK forwards `enableRemoteConfig` to the native iOS and Android Session Replay libraries. Amplitude's Session Replay privacy settings state that if you enable remote configuration and it fails to load, Session Replay doesn't capture sessions.

## Track web views (beta)

By default, Session Replay blocks web views and doesn't track them. To track a web view, wrap it in `AmpMaskView` and set `mask` to `amp-unmask`.

```js
import { AmpMaskView } from "@amplitude/session-replay-react-native";
import { WebView } from "react-native-webview";

<AmpMaskView mask="amp-unmask" style={{ flex: 1 }}>
  <WebView source={{ uri: "https://reactnative.dev/" }} style={{ flex: 1 }} />
</AmpMaskView>;
```

## EU data residency

Session Replay supports Amplitude projects that use the EU data center. Set `serverZone` to `'EU'` during initialization.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  serverZone: "EU",
});
await start();
```

## Sampling rate

By default, Session Replay captures 0% of sessions. Set `sampleRate` to the percentage of sessions you want to record.

```js
import { init, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
});
await start();
```

When you set `sampleRate`, consider the monthly quota on your Session Replay plan. For example, if your monthly quota is 2,500,000 sessions and you average 3,000,000 monthly sessions, your quota is 83% of your average sessions. To make sampling last through the month, set `sampleRate` to `.83` or lower.

Keep these quota details in mind:

- When you reach your monthly session quota, Amplitude stops capturing sessions for replay.
- Session quotas reset on the first of every month.
- Use sample rate to distribute your session quota across the month, rather than using your full quota at the beginning.
- Start with a low rate, for example `.01`. If this value doesn't capture enough replays, raise the rate over a few days. To monitor captured replay volume, go to [View the number of captured sessions](https://amplitude.com/docs/session-replay).

Session Replay supports remote sampling rate settings. Your organization can update the sampling rate of your project after implementation, without a code change. If there's a conflict, Session Replay defaults to the remote setting. For more information, go to [Account Settings](https://amplitude.com/docs/admin/account-management/account-settings#session-replay-settings).

## User opt-out

To skip collection at initialization, set `optOut` to `true`. To change this later, call `setOptOut()`. Don't re-run `init()` only to change opt-out.

```js
import { init, setOptOut, start } from "@amplitude/session-replay-react-native";

await init({
  apiKey: "AMPLITUDE_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  optOut: true,
});

await setOptOut(false);
await start();
```

## Troubleshooting

### No replay appears

- Call `start()` after `init()`. `init()` configures the SDK and doesn't begin capture.
- Use a non-zero `sampleRate`, or confirm the remote sampling rate on the Session Replay settings page.
- Pass the same `deviceId` and `sessionId` that your analytics events use, and update both when they change.
- Rebuild the native app after you install the package. On iOS, run `pod install` before the rebuild.
- Don't run this SDK in Expo Go. Create a development build or prebuild client instead.

================================================================================
# Flutter Session Replay
URL: https://amplitude.com/docs/sdks/session-replay/session-replay-flutter-standalone-sdk
Updated: 2026-11-04
================================================================================

# Flutter Session Replay

- **Package:** `amplitude_session_replay` ([pubdev](https://pub.dev/packages/amplitude_session_replay))
- **Latest version:** 1.0.1

Flutter Session Replay records application sessions on iOS and Android. Connect replays to your Amplitude events by sharing device and session IDs. Use [add-to-app](#add-to-app) when an iOS or Android host app manages recording.

Use the current stable release, `1.0.1`, of the [`amplitude_session_replay`](https://pub.dev/packages/amplitude_session_replay) package. If you're upgrading from a beta, refer to [Upgrade from earlier beta versions](#upgrade-from-earlier-beta-versions).

You need your Amplitude project's API key to initialize Flutter Session Replay. You must also set a device ID and an active session ID. To link replays with analytics events, use the same top-level `device_id` and `session_id` values. Follow [Connect Session Replay](#connect-session-replay) to use the IDs from Analytics Flutter.

Keep these IDs synchronized when your application starts a new session or changes identity. To report issues, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new).

## Compatibility

| Requirement | Minimum version |
| --- | --- |
| Dart SDK | 3.7.2 |
| Flutter SDK | 3.29.2 |
| iOS | 13.0 |
| Android minSdk | 21 (Android 5.0) |
| Android compileSdk | 36 |

Widgets that use `RSuperellipse` require Flutter 3.32 or later. Flutter-only recording captures the primary Flutter view; for multiple-engine host applications, follow [Add-to-app](#add-to-app).

## Quickstart

### Configure your Amplitude project

In [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings), enable session capture for your project and set its sampling rate. Configure its masking level using [Manage privacy settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay#masking-levels).

By default, Flutter Session Replay reads sampling and masking settings from the Amplitude project identified by your `apiKey`. Set that project's sampling rate above 0% before starting recording.

### Install and initialize

Add Flutter Session Replay to your `pubspec.yaml`:

```yaml
dependencies:
  amplitude_session_replay: ^1.0.1
```

Then run `flutter pub get`.

`SessionReplay` is a process-wide singleton. Access it through `SessionReplay.instance`, and don't construct it directly.

Configure your application code:

1. Call `SessionReplay.instance.init()` with a `SessionReplayConfig`, passing your API key, device ID, and session ID. `init()` is synchronous.
2. Call `start()` to request recording.
3. When the session ID or device ID changes, call `setSessionId()` or `setDeviceId()` to keep Session Replay synchronized.

> **Note:** Analytics identifiers
>
> The examples use an initialized [Analytics Flutter client](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4#initialize-the-sdk) named `analytics`. Read its device and session IDs before configuring Replay. Later configuration examples reuse the validated `deviceId` and `sessionId` from this setup. If you use another analytics provider, supply that provider's matching IDs.

```dart
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_session_replay/amplitude_session_replay.dart';

Future<void> startReplay(Amplitude analytics) async {
  await analytics.isBuilt;
  final deviceId = await analytics.getDeviceId();
  final sessionId = await analytics.getSessionId();
  if (deviceId == null || sessionId == null || sessionId <= 0) return;

  SessionReplay.instance.init(
    SessionReplayConfig(
      apiKey: 'YOUR_AMPLITUDE_API_KEY',
      deviceId: deviceId,
      sessionId: sessionId,
      privacyConfig: PrivacyConfig.conservative,
    ),
  );
  await SessionReplay.instance.start();
}
```

### Debug recording

> **Note:** Debug sessions only
>
> For local debugging, disable remote configuration and set `sampleRate: 1.0` to select every test session. Use the same development project for Analytics and Replay, and keep the required masking level.

Supply a production configuration with the same project API key, server zone, and current device and session IDs as the Analytics client.

```dart
import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/foundation.dart';

Future<void> startReplayForBuild(
  SessionReplayConfig productionConfig,
) async {
  final config = kDebugMode
      ? SessionReplayConfig(
          apiKey: 'YOUR_DEVELOPMENT_AMPLITUDE_API_KEY',
          deviceId: productionConfig.deviceId,
          sessionId: productionConfig.sessionId,
          enableRemoteConfig: false,
          sampleRate: 1.0,
          privacyConfig: PrivacyConfig.conservative,
        )
      : productionConfig;

  SessionReplay.instance.init(config);
  await SessionReplay.instance.start();
}
```

## Connect Session Replay

To link replays with analytics events, use the same project API key, server zone, device ID, and session ID for both SDKs. Refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

Use the current [Analytics Flutter SDK](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4#initialize-the-sdk) and read its [session ID](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4#track-sessions) and [device ID](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4#custom-device-id) with `getSessionId()` and `getDeviceId()`. Update Replay's IDs when Analytics changes them. Stop recording during identity changes and resume after the IDs match. Apply consent changes to both SDKs.

For applications that embed Flutter in an iOS or Android host, follow [Add-to-app](#add-to-app).

## Configuration

Pass the following options through `SessionReplayConfig` when you call `SessionReplay.instance.init()`:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `apiKey` | `String` | Yes | — | Your Amplitude API key for authentication and data routing. |
| `deviceId` | `String` | Yes | — | Device identifier of at least 6 characters. To link replays with analytics events, use the same device ID. |
| `sessionId` | `int` | No | `-1` | Session identifier in milliseconds since epoch. A value of `-1` means no active session, and Session Replay doesn't record. To link replays with analytics events, use the same session ID. |
| `sampleRate` | `double` | No | `0.0` | Local fraction of sessions to capture (0.0–1.0). Project remote settings take precedence. For example, `0.4` selects 40% of sessions when remote configuration is disabled. The local default selects no sessions. |
| `logLevel` | `LogLevel` | No | `LogLevel.warn` | Logging verbosity. Options: `LogLevel.off`, `LogLevel.error`, `LogLevel.warn`, `LogLevel.log`, `LogLevel.debug`. |
| `privacyConfig` | `PrivacyConfig` | No | `PrivacyConfig.medium` | Automatic masking behavior. Options: `PrivacyConfig.conservative`, `PrivacyConfig.medium`, `PrivacyConfig.light`. |
| `enableRemoteConfig` | `bool` | No | `true` | Enables [remote configuration](#remote-configuration) from Amplitude servers. |
| `optOut` | `bool` | No | `false` | Opt users out of recording and uploads. Use `setOptOut()` to change at runtime. |
| `serverZone` | `ServerZone` | No | `ServerZone.us` | Server zone for data residency. Set to `ServerZone.eu` for EU data center. |

### Remote configuration

With `enableRemoteConfig: true`, the project's remote settings take precedence over local sampling and privacy settings. Manage those settings in [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings).

The default local privacy level is `PrivacyConfig.medium`. Set the required `privacyConfig` before starting recording, and use privacy wrappers for sensitive content. Local masking applies until the project's remote privacy setting arrives, so the local level must protect content from the start.

For local testing, follow [Debug recording](#debug-recording).

### Mask onscreen data

Session Replay provides three Flutter widgets for privacy control. These widgets apply to the entire subtree of the wrapped widget. Priority order: `AmpBlock` > `AmpMask` > `AmpUnmask`.

#### Privacy levels

The `privacyConfig` option controls automatic masking behavior:

| Level | Behavior |
| --- | --- |
| `PrivacyConfig.conservative` | Masks all text and all form fields. |
| `PrivacyConfig.medium` (default) | Masks all form fields and text inputs. |
| `PrivacyConfig.light` | Masks only password fields. |

#### AmpMask

Masks Flutter text with a rectangle matching the text bounds. Use `AmpMask` for sensitive text that the automatic privacy level doesn't cover:

```dart
AmpMask(
  child: Text('Sensitive information'),
)
```

Images don't receive automatic masking at any privacy level. Wrap sensitive images or image-containing subtrees in `AmpBlock`. `AmpMask` doesn't hide image content.

#### AmpBlock

Blocks an entire subtree from recording and replaces it with a placeholder. Use this for highly sensitive content:

```dart
AmpBlock(
  child: TextField(
    decoration: InputDecoration(labelText: 'Password'),
  ),
)
```

#### AmpUnmask

Prevents automatic masking from privacy level rules. Use this to reveal content that the privacy level would otherwise mask. `AmpUnmask` can't override a manual `AmpMask` or `AmpBlock`:

```dart
AmpUnmask(
  child: Text('Public content'),
)
```

#### Platform views

Supported embedded platform views are blocked by default, including views without a Flutter privacy wrapper. Register the plugin before creating these views. The application UI stays visible. Use `AmpUnmask` only when the platform view and every descendant are safe to record. Wrapper precedence remains `AmpBlock` > `AmpMask` > `AmpUnmask`.

| Wrapper | Android platform views | iOS platform views |
| --- | --- | --- |
| `AmpMask` | Masks native text with asterisks. | Blocks the view with a gray placeholder. |
| `AmpBlock` | Blocks the view with a placeholder. | Blocks the view with a gray placeholder. |
| `AmpUnmask` | Permits recording of the view and its descendants. | Permits recording of the view and its descendants. |

To record maps, use Android Google Maps or iOS MapKit and wrap the view in `AmpUnmask`.

Keep sensitive platform views blocked from creation. Later masking can retain previously captured pixels. On Android, keep sensitive WebViews blocked rather than switching them to `AmpMask` after recording begins.

Platform views can appear above Flutter overlays in a replay. For installation requirements, refer to [Plugin registration](#plugin-registration).

### User opt-out

To opt users out of session replay collection, pass `optOut: true` during initialization, or call `setOptOut(optOut: true)` at runtime. Apply consent changes to both Replay and your analytics SDK. Stop capture before displaying restricted content.

```dart
await SessionReplay.instance.setOptOut(optOut: true);
```

### EU data residency

Amplitude customers who use the EU data center can access Session Replay. Set `serverZone` to `ServerZone.eu` during initialization.

```dart
SessionReplay.instance.init(
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: deviceId,
    sessionId: sessionId,
    serverZone: ServerZone.eu,
  ),
);
```

### Sampling rate

Set the project's sampling rate in [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings#sampling). Remote configuration is enabled by default and takes precedence over the local `sampleRate`.

For local testing, follow [Debug recording](#debug-recording) to disable remote configuration and select every test session.

### Update the session ID

When Analytics starts a new session, read its current session ID and pass it to Flutter Session Replay. In this example, `analytics` is your initialized Analytics Flutter client:

```dart
final sessionId = await analytics.getSessionId();
if (sessionId != null && sessionId > 0) {
  await SessionReplay.instance.setSessionId(sessionId);
}
```

If your application manages session IDs, pass the same updated ID to Replay and your analytics events. Refer to [Connect Session Replay](#connect-session-replay) for identity and session synchronization.

### Start and stop recording

Control recording for specific pages or features:

```dart
// Stop recording before entering a restricted area
await SessionReplay.instance.stop();

// Resume recording after leaving the restricted area
await SessionReplay.instance.start();
```

### Disable replay collection

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

- The user leaves your app.
- You call `SessionReplay.instance.stop()`.
- You call `SessionReplay.instance.dispose()`.

Call `SessionReplay.instance.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

Call `SessionReplay.instance.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

### Add-to-app

If your Flutter module runs inside an iOS or Android host app that already records Session Replay, call `SessionReplay.instance.attach()` instead of `init()`. Configure the API key, device ID, session ID, sampling, masking, and recording lifecycle in the host app.

```dart
import 'package:amplitude_session_replay/amplitude_session_replay.dart';
import 'package:flutter/widgets.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Connect Flutter to the host app's Session Replay recording.
  SessionReplay.instance.attach();

  runApp(const MyApp());
}
```

In add-to-app integrations, configure recording through the host app. Dart `start()`, `stop()`, `flush()`, `setOptOut()`, `setSessionId()`, and `setDeviceId()` have no effect. Dart `dispose()` disconnects Flutter without stopping the host's recording.

If your app runs multiple Flutter engines, call `attach()` in each entry point.

#### Plugin registration

Automatic Flutter plugin registration handles this setup for standard Flutter applications. For manual registration or add-to-app integrations, register `AmplitudeSessionReplayPlugin` with every Flutter engine before creating platform views and before recording starts.

In add-to-app integrations, call `attach()` in each Flutter entry point in addition to registering the plugin. Registering after view creation can leave those views unblocked. In add-to-app integrations, check the plugin's `isNativeViewBlockingAvailable` property before the host starts recording.

## Methods

Call these methods on the `SessionReplay.instance` singleton:

| Method | Returns | Description |
| --- | --- | --- |
| `init(SessionReplayConfig)` | `void` | Configure Flutter Session Replay. Synchronous and one-shot per lifecycle. Call `dispose()` before re-initializing with a new config. |
| `attach()` | `void` | Connect Flutter to recording managed by an iOS or Android host app. Use instead of `init()`. |
| `start()` | `Future<void>` | Request recording. |
| `stop()` | `Future<void>` | Stop recording. Call `start()` to resume. |
| `dispose()` | `Future<void>` | Release all resources and return the singleton to its uninitialized state. Call `init()` or `attach()` again to reuse it. |
| `flush()` | `Future<void>` | Request upload of pending replay data after `start()`. Check logs for upload errors. |
| `setSessionId(int)` | `Future<void>` | Update the session ID. |
| `sessionId()` | `Future<int>` | Get the current session ID. |
| `setDeviceId(String)` | `Future<void>` | Update the device ID. |
| `deviceId()` | `Future<String>` | Get the current device ID. |
| `setOptOut(optOut: bool)` | `Future<void>` | Request opt-out at runtime. Apply consent to your analytics SDK separately. |
| `optOut` (getter) | `bool` | Get the current opt-out status. |

### Lifecycle

![Flutter Session Replay lifecycle: init(config) creates the Initialized state, start() moves to Started, stop() moves to Stopped, start() returns Stopped to Started, dispose() from any state moves to Disposed, and init(config) revives Disposed back to Initialized.](https://amplitude.com/docs/images/diagrams/flutter-session-replay-lifecycle.svg) ![Flutter Session Replay lifecycle: init(config) creates the Initialized state, start() moves to Started, stop() moves to Stopped, start() returns Stopped to Started, dispose() from any state moves to Disposed, and init(config) revives Disposed back to Initialized.](https://amplitude.com/docs/images/diagrams/flutter-session-replay-lifecycle.dark.svg)

`init()` is one-shot per lifecycle: it's only callable from the uninitialized (or disposed) state. To re-initialize with a new config, call `dispose()` first, then `init()` again.

You can call `dispose()` from any state. It returns the singleton to its uninitialized state, so a later `init()` or `attach()` cleanly revives it. Use `dispose()` for permanent teardown only. To temporarily pause and resume recording, use `stop()` and `start()` instead.

## Upgrade from earlier beta versions

Version `0.1.0-beta.5` introduced the singleton API. `SessionReplay` is a process-wide singleton, and installation no longer requires the `SessionReplayWidget` wrapper.

Experimental configuration options have changed. If your integration uses experimental options, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) for help migrating.

### Breaking changes

For Flutter-only apps:

| Old API | New API |
| --- | --- |
| `SessionReplay(config)` constructor | `SessionReplay.instance.init(config)` |
| `SessionReplayWidget(sessionReplay: ..., app: ...)` | Removed. No widget wrapping needed |
| `sessionReplayProperties()` | Removed. Replays match by `deviceId` and `sessionId` |

For add-to-app:

| Old API | New API |
| --- | --- |
| `SessionReplayConfig.shouldInitializeNativeSDK: false` | Removed. Call `SessionReplay.instance.attach()` |
| `ensureInitialized()` | `SessionReplay.instance.attach()` |

### Flutter-only apps

Replace the constructor and `SessionReplayWidget` wrapper with `SessionReplay.instance.init()` and `start()`:

```dart
// Before
final sessionReplay = SessionReplay(
  SessionReplayConfig(apiKey: '...', sampleRate: 1.0),
);
runApp(SessionReplayWidget(sessionReplay: sessionReplay, app: const MyApp()));
await sessionReplay.start();

// After
SessionReplay.instance.init(          // synchronous, no await
  SessionReplayConfig(
    apiKey: 'YOUR_AMPLITUDE_API_KEY',
    deviceId: deviceId,
    sessionId: sessionId,
  ),
);
await SessionReplay.instance.start();
runApp(const MyApp());                // no SessionReplayWidget wrapping needed
```

- `init()` is one-shot per lifecycle. Call `await SessionReplay.instance.dispose()` before re-initializing with a new config.
- Setters (`setSessionId()`, `setDeviceId()`, `setOptOut()`) still work between `init()` and `start()`.

### Add-to-app

Replace the placeholder config and widget wrapper with a single `attach()` call:

```dart
// Before: placeholder config and widget wrapper
return SessionReplayWidget(
  sessionReplay: SessionReplay(
    const SessionReplayConfig(
      apiKey: 'AMPLITUDE_API_KEY',
      deviceId: 'YOUR_DEVICE_ID',
      shouldInitializeNativeSDK: false,
    ),
  ),
  app: MaterialApp(...),
);

// After: one line per entry point, no config needed
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SessionReplay.instance.attach(); // host manages config and lifecycle
  runApp(const MyApp());
}
```

- Call `attach()` in every Dart entry point.
- Remove conflicting dependency version pins in the host app so the Flutter package can install its required dependencies.

### Session Replay properties

Remove all calls to `sessionReplayProperties()`. Amplitude matches replays to analytics events by `deviceId` and `sessionId`. Make sure those match the identifiers you send with your analytics events. For more information, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching).

The `AmpMask`, `AmpUnmask`, and `AmpBlock` privacy widgets are unchanged.

## Data retention, deletion, and privacy

Review [consent guidance](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent) when you implement capture.

### Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the [Session Replay data lifecycle reference](https://amplitude.com/docs/session-replay/replay-data-lifecycle#native-and-flutter-sdk-retention).

### DSAR API

For replay metadata returned by the DSAR API, go to [Session Replay DSAR metadata](https://amplitude.com/docs/session-replay/replay-data-lifecycle#dsar-api).

### 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).

## Troubleshooting

### Session replays don't appear in Amplitude

Session replays may not appear because of:

- Lack of network connectivity.
- Sampling excluded the session (`sampleRate` too low).
- No events sent with matching `deviceId` and `sessionId` for the session.
- A missing `SessionReplay.instance.start()` call after `init()`.

#### Verify your configuration

1. Check that your project sampling rate is greater than 0%. If you disabled remote configuration, set the local `sampleRate` above `0.0`.
2. Confirm you call `SessionReplay.instance.start()` after `SessionReplay.instance.init()`.
3. Ensure the `apiKey`, `deviceId`, and `sessionId` match the values you send with analytics events.

#### Verify network connectivity

Ensure your app has access to the internet and try again.

#### Check sample rate

When remote configuration is enabled, check the sampling rate in [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings#sampling). For local configuration, set `sampleRate` above its `0.0` default. Refer to [Sampling rate](#sampling-rate).

### Session Replay processing errors

Replays appear in Amplitude within minutes of ingestion. Delays or errors may result from:

- Mismatched API keys or device IDs between Session Replay and your analytics instrumentation.
- Session Replay references the wrong project.
- Short sessions. If a user bounces within a few seconds of initialization, the SDK may not have time to upload replay data.

### Platform view blocking is unavailable

If recording stops with `NATIVE_VIEW_BLOCKING_UNAVAILABLE`, check that `AmplitudeSessionReplayPlugin` registers with every engine before platform-view creation. Confirm your Flutter version meets the compatibility requirements and remove conflicting dependency version pins.

Keep recording disabled until blocking is available. If the issue continues, contact [Amplitude support](https://gethelp.amplitude.com/hc/en-us/requests/new) with your Flutter version and logs. In add-to-app integrations, check the plugin's `isNativeViewBlockingAvailable` property before the host starts recording.

### Flush returns but no replay appears

Call `flush()` after `start()` to request upload of pending replay data. Check logs, connectivity, sampling, and matching analytics events if the replay doesn't appear. In add-to-app integrations, request the upload through the host app.

================================================================================
# Troubleshoot Session Replay
URL: https://amplitude.com/docs/session-replay/troubleshooting
Updated: 2026-10-05
================================================================================

# Troubleshoot Session Replay

Use the replay's error message and the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor) to diagnose missing or incomplete recordings. The monitor shows request statuses over time; the sections here explain common playback symptoms and fixes.

## Session Replay processing errors

Browser replays generally appear within minutes of ingestion. Delays or errors can result from these causes:

| Possible cause | What happens |
| --- | --- |
| Mismatched API keys or device IDs | Session Replay and standard event instrumentation use different API keys or device IDs. |
| Wrong project | Session Replay references the wrong project. |
| Short sessions | If a user leaves within a few seconds of initialization, the SDK may not have time to upload replay data. |
| Page instrumentation | If Session Replay doesn't run on every page a user visits, the session may not capture properly. |
| Retention period | The replay is older than the configured [retention period](https://amplitude.com/docs/session-replay/replay-data-lifecycle#retention-period). |

For browser-specific capture and identity diagnostics, follow the [browser plugin troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#troubleshooting) or [standalone browser SDK troubleshooting guide](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#troubleshooting), depending on your implementation.

## CSS styling doesn't appear in a replay

For browser replays with missing or incorrect CSS, follow the styling diagnostics for the [browser plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#css-styling-doesnt-appear-in-a-replay) or [standalone browser SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk#css-styling-doesnt-appear-in-replay).

## Parts of this session weren't captured

Missing portions may appear as inactive periods because Amplitude didn't capture user interaction during that period. The issue can also affect the entire replay.

| Possible cause | What happens |
| --- | --- |
| User closes the browser | Amplitude captures and uploads while the user uses your product. Leaving the app or closing the browser before an upload completes can leave portions unavailable for playback. |
| Network issues | Network degradation on the user's site or app can prevent replay data from uploading. |
| Request throttling | A traffic spike during a holiday, special event, or other peak period can cause Amplitude to throttle uploads to maintain system performance. |

To investigate:

1. Check the Ingestion Monitor for a spike in `429` throttling errors. Follow [Short or incomplete replays](#short-or-incomplete-replays) if you find throttling.
2. Leave thumbs-down feedback in the replay if the recording doesn't meet expectations.
3. Contact [Amplitude Support](https://gethelp.amplitude.com/hc/en-us) if network failures recur or you suspect missing replay data.

If you expect high traffic from a campaign or event, contact Amplitude Support for a temporary change to the throttle threshold.

## Short or incomplete replays

For replays shorter than 10 seconds or recordings that appear incomplete, check the Ingestion Monitor for `429` errors.

A `429` error means your application sends too many Session Replay requests. Amplitude throttles the requests. Replays consist of multiple data chunks, so failed requests can produce incomplete or unusually short recordings.

1. [Reduce your Session Replay sample rate](https://amplitude.com/docs/session-replay/configure-sampling) to lower request volume per second.
2. Monitor the `429` error count to confirm that throttling decreases after the adjustment.

## Replay temporarily unavailable due to ingestion delay

This message appears for a replay that Amplitude ingested within the last five minutes. Amplitude takes one or two minutes to make a replay ready for playback.

Live replays longer than five minutes become playable after Amplitude receives enough data to generate the replay. Refresh the page for the most recent data.

================================================================================
# Manage Session Replay settings
URL: https://amplitude.com/docs/session-replay/session-replay-settings
Updated: 2026-10-05
================================================================================

# Manage Session Replay settings

Use Session Replay settings to control which projects capture replays and heatmap data, manage your capture quota, and choose privacy controls. Use these settings to adjust an existing implementation. To start capturing replays, first [install the Session Replay browser plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#quickstart).

## Open Session Replay settings

Admins and managers can view or modify settings for projects they have access to.

1. Go to _Settings > Organizational Settings > Session Replay Settings_.
2. Review your organization's replay capture allowance and current usage.
3. Find the project you want to configure. The project list shows capture toggles, sample rate, instrumentation status, masking level, and masking overrides.
4. Select the project to open its sampling, masking, and console tracking controls.

## Control replay and heatmap capture

Use the project list to enable or disable session capture and heatmap capture for each project.

[Heatmaps](https://amplitude.com/docs/heatmaps) aggregate web Session Replay interactions into maps of clicks, element interactions, and scroll depth. Enabling heatmap capture controls data collection; to check SDK requirements and build a map, follow [Create a heatmap](https://amplitude.com/docs/heatmaps/create-a-heatmap). Replay sampling limits the interactions available to heatmaps, so consider heatmap coverage when choosing a sample rate.

After you change capture settings, [verify capture](https://amplitude.com/docs/session-replay/verify-capture). If the SDK sends replay requests but replays don't appear, use [Monitor replay ingestion](https://amplitude.com/docs/session-replay/ingestion-monitor) to check request statuses.

## Choose sampling and targeting

In the project's _Sampling_ control, choose how to distribute your replay capture quota:

- Use [manual sampling](https://amplitude.com/docs/session-replay/configure-sampling#choose-a-manual-rate-for-your-quota) to capture a fixed percentage of sessions.
- Use [dynamic sampling](https://amplitude.com/docs/session-replay/configure-sampling#dynamic-sampling) to adjust rates daily across participating projects.
- Use [targeted capture](https://amplitude.com/docs/session-replay/targeted-replay-capture) to capture sessions that match events, properties, or URLs.

For quota calculations and configuration requirements, follow [Configure Session Replay sampling](https://amplitude.com/docs/session-replay/configure-sampling). To check capture volume after changing rates, [measure captured replays](https://amplitude.com/docs/session-replay/measure-replay-capture).

## Configure masking

In the project settings, choose a masking level and define overrides for individual page elements. Follow [Manage privacy settings for Session Replay](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay) for masking presets, CSS selectors, and precedence between SDK and organization settings.

Masking controls page text and form inputs. To protect sensitive content in URLs, [configure URL filter rules](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules). To determine when to start capture based on consent, follow [Manage user consent](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent).

## Configure console tracking

Capture console information when you need to investigate an error alongside the user's actions.

1. Go to _Settings > Organizational Settings > Session Replay Settings_.
2. Select the project you want to configure.
3. In _Console Tracking_, enable or disable console tracking.
4. Select the types of console information to capture: `Info`, `Log`, `Warn`, and `Error`.

To investigate the captured logs alongside network requests and replay activity, follow [Inspect replay errors](https://amplitude.com/docs/session-replay/inspect-replay-errors).

================================================================================
# Manage replay retention and deletion
URL: https://amplitude.com/docs/session-replay/replay-data-lifecycle
Updated: 2026-10-09
================================================================================

# Manage replay retention and deletion

Amplitude retains raw replay data for a defined period from ingestion and uses its existing APIs for privacy and deletion requests. Use this guidance to plan how long recordings remain available and handle requests to access or delete user data. It covers retention by SDK path, available metadata, and user or project deletion.

For privacy notices, disclosure examples, and consent controls, go to [Best practices for managing user consent](https://amplitude.com/docs/session-replay/best-practices-for-managing-user-consent).

## Retention period

If your Amplitude plan includes Session Replay, Amplitude retains raw replay data for 30 days from ingestion by default. Retention periods apply at the organization level. The retention clock starts when Amplitude receives the replay data, not when the session was captured.

### Browser and React Native plugin retention

You can purchase extra retention time, up to a maximum of 12 months. For more information, contact [Amplitude Support](https://support.amplitude.com).

If you purchase extra session volume, Amplitude retains raw replay data for up to 12 months from ingestion. For a stricter policy, contact Amplitude support to set retention to 30 days.

This guidance applies to the [browser plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin), [browser standalone SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk), and [React Native SDK plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-plugin).

### Native and Flutter SDK retention

For the native Android and iOS SDK paths and the Flutter standalone SDK, extra session volume includes 90 days of raw replay retention from ingestion. For a stricter policy, contact Amplitude support to set retention to 30 days.

### Effective date of retention changes

Changes to retention affect replays ingested after the change. Sessions captured and ingested before a retention change keep the previous retention period.

Replays outside the retention period aren't viewable in Amplitude. [Bookmarked replays](https://amplitude.com/docs/session-replay/bookmarkable-session-replays) aren't subject to the retention period. They stay available until you remove the bookmark. Commenting on a replay doesn't bookmark it, but it keeps the replay for at least 360 days after the session ends. For details, go to [Comment on replays](https://amplitude.com/docs/session-replay/comment-on-replays).

## DSAR API

The Amplitude [DSAR API](https://amplitude.com/docs/apis/analytics/ccpa-dsar) returns metadata about session replays, but not raw replay data.

Amplitude automatically creates the `[Amplitude] Replay Captured` event when Session Replay captures a session. This event includes the `[Amplitude] Session Replay ID` property, which provides information about replays collected for the user.

In native and Flutter SDK implementations, events that are part of a session replay include the `[Amplitude] Session Replay ID` event property and the metadata collected with each event.

The replay ID has the format `<deviceId>/<sessionId>`. For custom ID constraints and configuration, go to [Configure custom Session Replay matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching).

Example replay metadata:

```json
{
 "amplitude_id": 123456789,
 "app": 12345,
 "event_time": "2020-02-15 01:00:00.123456",
 "event_type": "first_event",
 "server_upload_time": "2020-02-18 01:00:00.234567",
 "device_id": "your device id",
 "user_properties": { ... },
 "event_properties": {
 "[Amplitude] Session Replay ID": "cb6ade06-cbdf-4e0c-8156-32c2863379d6/1699922971244"
 },
 "session_id": 1699922971244,
}
```

## Data deletion

Session Replay uses Amplitude's [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy) for deletion requests. Successful requests remove all session replays for the specified user.

When you delete an Amplitude project that uses Session Replay, Amplitude deletes that project's replay data.

## Bot filter

Session Replay uses the same [block filter](https://amplitude.com/docs/data/block-bot-traffic) as the Amplitude app. Session Replay doesn't block traffic based on event or user properties.

================================================================================
# Look up URL filter rules
URL: https://amplitude.com/docs/session-replay/ugc-filter-rules
Updated: 2026-11-04
================================================================================

# Look up URL filter rules

Use `ugcFilterRules` to replace sensitive URL content, such as user IDs or private query parameters, before the SDK records URLs in replays and heatmaps. This reference explains rule syntax, ordering, and validation. For installation and testing steps, [configure URL filtering](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules).

## What UGC Filter Rules do

UGC Filter Rules are configuration objects that define patterns to match URLs and specify replacement text. When the SDK captures URLs during session replay and heatmap recording, the SDK applies these rules to sanitize or anonymize sensitive information such as:

- User IDs
- Company names
- Sensitive query parameters
- Dynamic path segments containing private data

## Configure UGC Filter Rules

The Standalone SDK, the Browser SDK plugin, and the Unified SDK's `sessionReplay` options all accept `interactionConfig.ugcFilterRules`. For initialization examples for each SDK and development checks, go to [Configure UGC Filter Rules](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules).

## Rule structure

Each UGC Filter Rule is an object with two required properties:

```typescript
type UGCFilterRule = {
  selector: string; // Glob pattern to match URLs
  replacement: string; // Text to replace the matched URL
};
```

### Properties

| Property | Description |
| --- | --- |
| `selector` | A glob pattern string that matches URLs. Supports `*` (any characters). Supports multiple wildcards in domains and paths. |
| `replacement` | The replacement text that the SDK uses when the selector pattern matches a URL. |

### Selector pattern examples

- `https://*.domain.com/*` matches any subdomain and any path.
- `https://site.com/*/*` matches two path segments.
- `https://api.com/*/data/*` matches specific patterns with wildcards.

## Glob pattern syntax

The `selector` field uses basic glob patterns for URL matching. The current implementation supports:

| Pattern | Description | Example |
| --- | --- | --- |
| `*` | Matches any sequence of characters | `https://example.com/*` matches `https://example.com/anything` |

Supported wildcard locations:

| Location | Description | Example |
| --- | --- | --- |
| Multiple wildcards | Use multiple `*` in a single pattern | `https://*.domain.com/*/*` |
| Domain wildcards | `*` works in domain names | `*.projecttool.com` |
| Path wildcards | Multiple `*` in URL paths | `/projects/*/boards/*` |

The SDK doesn't support advanced glob features such as `**`, `[abc]`, `{option1,option2}`, and others.

## Examples

### Filter project management tool URLs

Remove organization names and sensitive identifiers from project management URLs:

```javascript
// Filter ticket URLs
{
  selector: "https://*.projecttool.com/browse/*",
  replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER"
}

// Filter project list URLs
{
  selector: "https://*.projecttool.com/software/projects/*/list*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/list"
}

// Filter board URLs
{
  selector: "https://*.projecttool.com/software/projects/*/boards/*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/boards/BOARD_ID"
}

// Filter wiki pages
{
  selector: "https://*.projecttool.com/wiki/spaces/*/pages/*",
  replacement: "https://ORG_NAME.projecttool.com/wiki/spaces/SPACE_NAME/pages/PAGE_NAME"
}
```

### Filter code repository URLs

Remove repository details and sensitive paths:

```javascript
// Filter repository file browser with branch and file paths
{
  selector: "https://codehost.com/*/*/tree/*/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES"
}

// Filter repository branch view
{
  selector: "https://codehost.com/*/*/tree/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH"
}
```

### Filter user IDs from profile URLs

Remove user IDs from profile URLs:

```javascript
{
  selector: 'https://myapp.com/user/*/profile',
  replacement: 'https://myapp.com/user/USER_ID/profile'
}
```

Before: `https://myapp.com/user/12345/profile`  
After: `https://myapp.com/user/USER_ID/profile`

### Sanitize query parameters

Remove sensitive query parameters:

```javascript
{
  selector: 'https://myapp.com/dashboard?token=*',
  replacement: 'https://myapp.com/dashboard?token=REDACTED'
}
```

Before: `https://myapp.com/dashboard?token=abc123xyz`  
After: `https://myapp.com/dashboard?token=REDACTED`

### Filter URLs with multiple path segments

Filter URLs with multiple dynamic segments:

```javascript
{
  selector: 'https://api.example.com/users/*/documents/*/*',
  replacement: 'https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID'
}
```

Before: `https://api.example.com/users/john123/documents/private/contract-2023.pdf`  
After: `https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID`

### Filter email addresses in URLs

Remove email addresses from URL paths:

```javascript
{
  selector: 'https://myapp.com/user/*/settings',
  replacement: 'https://myapp.com/user/EMAIL_ADDRESS/settings'
}
```

Before: `https://myapp.com/user/john.doe@company.com/settings`  
After: `https://myapp.com/user/EMAIL_ADDRESS/settings`

## Advanced usage

### Rule precedence with multiple rules

The SDK applies rules in order, and the first matching rule wins:

```javascript
ugcFilterRules: [
  // More specific rule - will match first
  {
    selector: "https://example.com/user/*/profile/settings",
    replacement: "https://example.com/user/USER_ID/profile/settings",
  },
  // Less specific rule - will only match if first rule doesn't
  {
    selector: "https://example.com/user/*/*",
    replacement: "https://example.com/user/USER_ID/ACTION",
  },
];
```

### Complete configuration example

```javascript
import { sessionReplay } from "@amplitude/session-replay-browser";

sessionReplay.init("AMPLITUDE_API_KEY", {
  interactionConfig: {
    enabled: true,
    ugcFilterRules: [
      // Filter project management tool URLs
      {
        selector: "https://*.projecttool.com/browse/*",
        replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER",
      },
      {
        selector: "https://*.projecttool.com/software/projects/*/boards/*",
        replacement:
          "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/boards/BOARD_ID",
      },

      // Filter code repository URLs
      {
        selector: "https://codehost.com/*/*/tree/*/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES",
      },
      {
        selector: "https://codehost.com/*/*/tree/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH",
      },

      // Filter internal application URLs
      {
        selector: "https://myapp.com/user/*/profile",
        replacement: "https://myapp.com/user/USER_ID/profile",
      },
      {
        selector: "https://api.myapp.com/*?token=*",
        replacement: "https://api.myapp.com/ENDPOINT?token=REDACTED",
      },

      // Filter admin URLs completely
      {
        selector: "https://myapp.com/admin/*",
        replacement: "https://myapp.com/admin/ADMIN_SECTION",
      },
    ],
  },
});
```

## Error handling and validation

The SDK validates UGC Filter Rules during initialization.

### Validation rules

| Rule | Requirement |
| --- | --- |
| Type validation | Both `selector` and `replacement` must be strings. |
| URL format validation | The `selector` must be a valid URL pattern that starts with `/`, `http://`, or `https://`. |
| Non-empty | Selectors can't be empty or whitespace-only. |

### Error examples

```javascript
// ❌ Invalid - non-string selector
{
  selector: 123,
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties

// ❌ Invalid - non-string replacement
{
  selector: 'https://example.com/*',
  replacement: 456
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties

// ❌ Invalid - selector doesn't start with / or http(s)://
{
  selector: 'example.com/path',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs

// ❌ Invalid - empty selector
{
  selector: '',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs

// ❌ Invalid - whitespace-only selector
{
  selector: '   ',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs
```

## Best practices

### Order rules by specificity

Place more specific patterns before general ones:

```javascript
ugcFilterRules: [
  // More specific patterns first
  {
    selector: "https://codehost.com/*/*/tree/*/*",
    replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES",
  },
  // Less specific patterns later
  {
    selector: "https://codehost.com/*/*/tree/*",
    replacement: "https://codehost.com/USER/REPO/tree/BRANCH",
  },
  // Most general patterns last
  {
    selector: "https://codehost.com/*/*",
    replacement: "https://codehost.com/USER/REPO",
  },
];
```

### Use descriptive replacements

Make replacements clear and meaningful:

```javascript
// ✅ Good - descriptive
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER'
}

// ❌ Avoid - unclear
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://XXX.projecttool.com/browse/XXX'
}
```

### Test patterns in a development environment first

Go to [Test patterns in a development environment first](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules#test-patterns-in-a-development-environment-first) for example URLs to check.

## Common issues

| Issue | Resolution |
| --- | --- |
| Rules not applied | Ensure `interactionConfig.enabled` is `true`. |
| Pattern not matching | Use only `*` patterns. |
| Wrong order | Check that specific rules come before general ones. |
| Invalid patterns | Verify that selectors only use supported glob syntax (`*`). |

## Limitations

- The SDK applies rules to full URLs, not individual URL components.
- The SDK supports only `*` (any characters) for glob patterns.
- The SDK doesn't support advanced glob features such as `**`, `[abc]`, `{option1,option2}`, ranges, and negation.
- Rules can't modify URL structure. Rules can only replace entire URLs.

The SDK uses a simple glob-to-regex conversion that supports multiple wildcards and domain patterns.

================================================================================
# Monitor replay ingestion
URL: https://amplitude.com/docs/session-replay/ingestion-monitor
Updated: 2026-10-05
================================================================================

# Monitor replay ingestion

The Ingestion Monitor tracks Session Replay request statuses over time. Use it to monitor capture and delivery health. For symptom-specific fixes, follow [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting).

Access the Ingestion Monitor from:

- The top-right of the Session Replay section of your project's _Users & Sessions_ tab.
- Any individual replay that displays an error.

## Tracked statuses

The Ingestion Monitor displays charts with the count of each status over a time range that you select:

- Successful request (status 200)
- Throttling errors (status 429)
- Quota exceeded errors (status 402)
- Invalid session IDs

Use these charts to debug unavailable replays and check delivery after you [verify capture](https://amplitude.com/docs/session-replay/verify-capture). To count distinct captured recordings rather than SDK requests, [measure replay capture](https://amplitude.com/docs/session-replay/measure-replay-capture).

## Troubleshooting

### Short or incomplete replays

Check the monitor for `429` errors, then follow [Short or incomplete replays](https://amplitude.com/docs/session-replay/troubleshooting#short-or-incomplete-replays) to reduce throttling and confirm the result.

================================================================================
# Use the Replay Captured event
URL: https://amplitude.com/docs/session-replay/replay-captured-event
Updated: 2026-10-05
================================================================================

# Use the Replay Captured event

Use `[Amplitude] Replay Captured` to identify sessions with a replay you can watch and measure how many distinct replays Amplitude captures. Amplitude sends the event automatically after a successful capture, so you don't need to instrument it yourself.

For example, after changing your sample rate, count distinct replay IDs to check how capture volume changes. Use the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor) to diagnose request failures; the capture event identifies successful captures rather than failed attempts.

## Event identity and properties

| Field | Behavior |
| --- | --- |
| `[Amplitude] Session Replay ID` | Links the event to the captured replay. |
| Device ID | Uses the device ID passed to the Session Replay SDK or browser SDK plugin. |
| Session ID | Amplitude adds the session ID based on your project's Amplitude session definition. |
| User ID | The event doesn't use user ID. |

The event may create anonymous users if Amplitude can't associate the device ID with an existing user. The event doesn't count toward event volume or MTU (Monthly Tracked Users).

## Analyze captured replays

The capture event connects analysis to a replay through `[Amplitude] Session Replay ID`. Use it for these tasks:

- Investigate a user's experience: find the event in the user's event stream, then open the associated replay. Follow [Find replays with User Look-Up](https://amplitude.com/docs/session-replay/find-replays#view-session-replay-from-user-look-up) for the workflow.
- Track capture volume: select `[Amplitude] Replay Captured` in an Event Segmentation chart, group by `[Amplitude] Session Replay ID`, and use `PROPCOUNT(A)` to count distinct replay IDs. Follow [Measure replay capture](https://amplitude.com/docs/session-replay/measure-replay-capture) for the steps.
- Focus analysis on captured sessions: use the event to identify sessions with replays when investigating behavior in charts. Follow [Watch replays from a chart](https://amplitude.com/docs/session-replay/find-replays#view-session-replay-from-a-chart) to open the replay behind a data point.

Count distinct replay IDs when you need a replay count. A raw event count can include multiple capture events in a user's timeline.

## Multiple capture events in a timeline

Multiple `[Amplitude] Replay Captured` events can appear when multiple browser tabs have different active sessions. For how Amplitude associates analytics events with a replay, refer to [Session matching](https://amplitude.com/docs/session-replay/session-matching). Timelines show events captured during the replay period, so events from different sessions may overlap.

================================================================================
# Build direct replay links
URL: https://amplitude.com/docs/session-replay/replay-link-reference
Updated: 2026-10-05
================================================================================

# Build direct replay links

Construct a direct URL to share a specific replay programmatically or embed its link in an external tool. To copy a link from Amplitude, follow [Share session replays](https://amplitude.com/docs/session-replay/share-replays).

## URL structure

```text
https://app.[eu.]amplitude.com/analytics/<orgUrl>/session-replay/project/<projectId>/search/replay?sessionReplayId=<replayId>
```

| Placeholder | Description | How to find it |
| --- | --- | --- |
| `eu.` | Include this subdomain only for EU-based Amplitude accounts. Omit it otherwise. | Check the URL when logged in to Amplitude. EU accounts use `app.eu.amplitude.com`. |
| `<orgUrl>` | Your organization's URL identifier. | Find it in the browser URL when logged in, such as `https://app.amplitude.com/analytics/myorg/...`. |
| `<projectId>` | The numeric ID of the project that captured the replay. | Go to _Settings > Projects_, select the project, and copy the ID from the URL or project details page. |
| `<replayId>` | The session replay ID. | Use the `[Amplitude] Session Replay ID` property on a `[Amplitude] Replay Captured` event. |

## Example

```text
https://app.amplitude.com/analytics/myorg/session-replay/project/123456/search/replay?sessionReplayId=abc123def456
```

================================================================================
# Search replays with the API
URL: https://amplitude.com/docs/session-replay/replay-search-api
Updated: 2026-10-05
================================================================================

# Search replays with the API

Query the Replay Search API to find recordings for an automated investigation or external workflow. Filter by user properties, cohort membership, events, duration, or sentiment.

For an interactive investigation in Amplitude, [find replays with search filters](https://amplitude.com/docs/session-replay/find-replays#search-for-a-replay). Use this API when your application or agent needs to retrieve matching replay links.

## How the Replay Search API works

The API runs a query against Amplitude Analytics to find sessions matching your filters, then looks up Session Replay recordings for those sessions. The analytics query caps results at 1,000 sessions, so replay-level filters like `duration` apply to that capped set. The response metadata surfaces pre- and post-filter counts so you can tell when the cap affected your results.

## Request

`POST https://amplitude.com/api/1/replay-search`

For EU data residency, use `https://eu.amplitude.com/api/1/replay-search` instead.

### Full request shape

```json
{
  "start": "20260313",
  "end": "20260320",

  "userFilters": [
    { "type": "cohort", "cohortId": "abc123" },
    {
      "type": "property",
      "prop": "country",
      "op": "is",
      "values": ["United States"]
    }
  ],

  "eventFilters": [
    {
      "eventType": "Purchase",
      "op": "greater or equal",
      "count": 1,
      "filters": [
        { "type": "event", "prop": "page", "op": "is", "values": ["checkout"] },
        {
          "type": "user",
          "prop": "country",
          "op": "is",
          "values": ["United States"]
        }
      ]
    }
  ],

  "replayFilters": [
    { "prop": "duration", "op": "greater or equal", "values": ["10"] },
    { "prop": "sentiment", "op": "is", "values": ["positive"] }
  ],

  "groupBys": {
    "eventPosition": "last",
    "properties": [
      { "type": "user", "value": "country" },
      { "type": "event", "value": "platform" }
    ]
  },

  "limit": 10
}
```

### Fields

`start` / `end` (string, required) : Date range in `YYYYMMDD` format.

`userFilters` (array, optional) : Filters that narrow the users in the returned sessions. Amplitude combines all entries with AND. Choose either of these filter types:

Cohort filter:

```json
{ "type": "cohort", "cohortId": "abc123" }
```

Supports `"negated": true` to exclude cohort members.

Property filter:

```json
{
  "type": "property",
  "prop": "country",
  "op": "is",
  "values": ["United States"]
}
```

The property must match on at least one event in the session and must never not-match on any event in the session. This requirement confirms the property held true throughout the session, which matters for properties that can change mid-session, such as plan tier.

`eventFilters` (array, optional) : Filters on event occurrence within the session. Each entry specifies an event type and a count condition that the session must satisfy. If you specify `Item Purchased >= 1` and `Add to Cart >= 2`, Amplitude guarantees the returned replays are for sessions where at least one `Item Purchased` event and at least two `Add to Cart` events occurred.

| Field | Description |
| --- | --- |
| `eventType` | The event name, or `"_all"` to match any event. |
| `op` | One of `"greater or equal"`, `"greater"`, `"less or equal"`, `"less"`, `"is"`, `"is not"`. |
| `count` | Integer threshold. |
| `filters` | Optional array of property conditions scoped to this event. `type` is `"event"` or `"user"`. |

`replayFilters` (array, optional) : Filters on replay-level properties. The backend determines which filters apply during the session query (pre-filters) and which apply after replay retrieval (post-filters). The response `metadata` reflects this distinction. Supported properties:

| `prop` | Description | Filter timing |
| --- | --- | --- |
| `duration` | Replay duration in seconds | Post |
| `sentiment` | User feedback sentiment | Pre |

`groupBys` (object, optional) : Enriches each session in the response with specified property values.

| Field | Description |
| --- | --- |
| `eventPosition` | `"first"` or `"last"`. Controls which event in the session to read property values from. Applies to all properties. |
| `properties` | Array of `{"type": "user" | "event", "value": "<property name>"}` objects. |

`limit` (number, optional, default: 10) : Maximum number of sessions to return.

---

## Response

### Full response shape

```json
{
  "data": [
    {
      "amplitude_id": "123456789",
      "session_replay_id": "abc-def-ghi",
      "session_start_time": 1742860800000,
      "session_end_time": 1742861243000,
      "duration": 443,
      "url": "https://app.amplitude.com/...",
      "groupBys": {
        "country": "United States"
      }
    },
    {
      "amplitude_id": "987654321",
      "session_replay_id": "xyz-uvw-rst",
      "session_start_time": 1742774400000,
      "session_end_time": 1742774821000,
      "duration": 421,
      "url": "https://app.amplitude.com/...",
      "groupBys": {
        "country": "Germany"
      }
    }
  ],
  "metadata": {
    "pre_filter_count": 1000,
    "pre_filter_capped": true,
    "post_filters_applied": ["duration"],
    "post_filter_count": 2,
    "limit": 10
  }
}
```

### Session fields

Each object in `data` includes:

| Field | Type | Description |
| --- | --- | --- |
| `amplitude_id` | string | Amplitude user ID. |
| `session_replay_id` | string | Unique identifier for the replay. |
| `session_start_time` | number | Session start time in milliseconds since epoch. |
| `session_end_time` | number | Session end time in milliseconds since epoch. |
| `duration` | number | Session duration in seconds. |
| `url` | string | Direct link to the replay in Amplitude. |
| `groupBys` | object | Property values requested through `groupBys`, keyed by property name. |

### `metadata` fields

| Field | Type | Description |
| --- | --- | --- |
| `pre_filter_count` | number | Number of sessions matched before post-filters applied. Capped at 1000. |
| `pre_filter_capped` | boolean | `true` if the pre-filter result hit the 1000-session cap. When `true` and `post_filters_applied` is non-empty, the returned sessions may not represent the full matching population. |
| `post_filters_applied` | string\[\] | Names of `replayFilters` applied as post-filters. |
| `post_filter_count` | number | Number of sessions remaining after post-filters applied. |
| `limit` | number | The limit applied to the response. |

### Pre-filter and post-filter counts

The API caps the initial session query at 1,000 sessions. Post-filters (such as `duration`) apply to that capped set. If `pre_filter_capped` is `true` and `post_filters_applied` is non-empty, additional matching sessions beyond the cap may exist that the API didn't evaluate.

For example, if `pre_filter_count` is 1000, `pre_filter_capped` is `true`, and `post_filter_count` is 2, narrow your date range or event filters to reduce the pre-filter population.

---

## Limitations

- **Pagination**: The API doesn't support pagination. The 1,000-session pre-filter cap combined with post-filtering can produce sparse results for broad queries. Narrow your date range or add event filters to reduce the pre-filter population.
- **Funnel-based session search**: Finding replays for funnel conversion or drop-off is a distinct use case with different semantics. This API doesn't support funnel-based session search. To investigate conversion or drop-off in Amplitude, [open replays from a Funnel Analysis chart](https://amplitude.com/docs/session-replay/find-replays#availability-in-amplitude-charts).
- **Ordered event sequences**: The API doesn't support optional step ordering (for example, "event A then event B").

================================================================================
# Choose a session matching option
URL: https://amplitude.com/docs/session-replay/session-matching
Updated: 2026-10-05
================================================================================

# Choose a session matching option

Session matching connects analytics events to the replay of the same user activity. Use it to move from a funnel drop-off or an error event to the recording that shows what the user experienced. A matching option that fits your analytics pipeline makes event-based replay searches return the relevant recordings.

If your pipeline sends Amplitude's default `session_id`, matching works automatically. Review the options below if you use a custom session definition or send events without session IDs. Install Session Replay with the [instrumentation guide](https://amplitude.com/docs/session-replay/instrument-session-replay) before you verify matching.

## How session replay querying works

When you [search for replays by event](https://amplitude.com/docs/session-replay/find-replays), Amplitude looks for recordings that span the time when those events occurred. Session matching determines how Amplitude associates those recordings with the analytics events.

For session-ID matching, Amplitude finds replays that meet all three criteria:

1. The replay has the same session ID as the events.
2. The replay starts before the first event you're analyzing.
3. The replay ends after the last event you're analyzing.

![Timeline of queried events from 2:00 PM to 2:05 PM. Of three replays with the same session ID, only the one that starts before the first event and ends after the last event matches.](https://amplitude.com/docs/images/diagrams/replay-query-matching.svg) ![Timeline of queried events from 2:00 PM to 2:05 PM. Of three replays with the same session ID, only the one that starts before the first event and ends after the last event matches.](https://amplitude.com/docs/images/diagrams/replay-query-matching.dark.svg)

These criteria preserve the context around the events. For example, if checkout events occur between 2:00 PM and 2:05 PM in one session, Amplitude returns replays with that session ID that start before 2:00 PM and end after 2:05 PM. You can watch the actions leading to checkout and what happened afterward.

[Time-based matching](#time-based-event-matching) uses the same device ID and overlapping time windows instead of requiring analytics events to include a session ID. The replay SDK still needs an ID to group and upload replay data. That replay ID doesn't need to appear on your analytics events.

## Choose a matching option

| Option | Use when | Setup |
| --- | --- | --- |
| Match Amplitude sessions (recommended) | Your pipeline sends session IDs and you want matching to respect your project's session definition. | Default `session_id` matching works automatically. For event-property sessions, [configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching). |
| Time-based event matching | Your pipeline sends timestamps without session IDs, such as events delivered through S3. | [Configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching) with a 30- or 60-minute window and a frontend replay session ID. |
| Session ID matching (legacy) | You need backward compatibility with Amplitude `session_id` matching. | No additional SDK changes required. |

## Session matching options

### Match Amplitude sessions (recommended)

Amplitude matches replays using your project's session definition, including sessions defined by event properties, timeout windows, or start and end events. If you use the default `session_id`, matching works automatically without additional SDK configuration.

### Requirements for custom session definitions

If your project defines sessions by an event property, the replay SDK must send the same session ID value as that property. For example, if analytics events use an order ID to group a checkout session, send that order ID to Session Replay too. A different value prevents Session Replay from matching that custom session.

[Configure custom session matching](https://amplitude.com/docs/session-replay/configure-custom-session-matching) describes the project settings, supported SDK versions, ID constraints, and platform setup. For other custom session definitions, review [how Amplitude defines sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions#configure-a-custom-session-definition).

### Time-based event matching

Time-based matching builds sessions using 30- or 60-minute windows of event activity. Amplitude links replays to events by device ID and overlapping time windows. This mode has slightly less precision at session boundaries than matching Amplitude sessions.

The standalone Session Replay SDK still needs a replay `sessionId`, even when analytics events don't include one. [Configure time-based matching](https://amplitude.com/docs/session-replay/configure-time-based-matching) describes how to generate the ID on the frontend and keep replay uploads aligned with your chosen window.

### Session ID matching (legacy)

This option matches the Amplitude `session_id`, even when it doesn't align with a custom session definition. It exists for backward compatibility and requires no additional SDK changes. Amplitude continues to support this option and isn't deprecating it, though Amplitude recommends newer options for most use cases.

## Configure session matching

The matching setting applies to all projects in your organization. A change affects matching for future replays, without changing historical data. You can reverse the change without losing data.

To configure and test the matching option:

1. Review the analytics events your pipeline sends. Identify whether they include the default `session_id`, a custom session-defining property, or timestamps without session IDs.
2. Go to _Organization Settings > Session Replay_.
3. Select the option from the [matching options table](#choose-a-matching-option) that fits your pipeline. For time-based event matching, select a 30- or 60-minute window.
4. Complete the [custom session matching setup](https://amplitude.com/docs/session-replay/configure-custom-session-matching) if you use an event-property session definition. Complete the [time-based matching setup](https://amplitude.com/docs/session-replay/configure-time-based-matching) if your analytics events have no session IDs. Default `session_id` matching requires no additional SDK setup.
5. [Capture a test session](https://amplitude.com/docs/session-replay/verify-capture#capture-a-test-session) and search for a known event from that session. Open the matching replay and check that the recorded activity corresponds to the event.

If the test replay doesn't match, compare the device IDs and session IDs your analytics pipeline and replay SDK send. For time-based matching, compare the device IDs and event timestamps. Use the [troubleshooting guide](https://amplitude.com/docs/session-replay/troubleshooting) if capture or playback also fails.