Set Up Session Replay

Session Replay helps you get to the root cause of an error or latency issue faster by providing you with a video-like reproduction of what was happening in the user's browser before, during, and after the issue. You can rewind and replay your application's DOM state and see key user interactions, like mouse clicks, scrolls, network requests, and console entries, in a single combined UI inspired by your browser's DevTools.

By default, our Session Replay SDK masks all DOM text content, images, and user input, giving you heightened confidence that no sensitive data will leave the browser. To learn more, see Session Replay Privacy.

Prerequisites

For the sentry-replay integration to work, you must have the Sentry Capacitor SDK package installed. The minimum version required for the SDK is 0.11.0. If you're on an older version of the SDK, please check the troubleshooting document to help on migration.

Install

Install the Sentry Capacitor SDK alongside the corresponding Sentry SDK for the framework you're using:

# npm
npm install @sentry/capacitor @sentry/angular --save

# yarn
yarn add @sentry/capacitor @sentry/angular

# pnpm
pnpm add @sentry/capacitor @sentry/angular

Set Up

To set up the integration, add the following to your Sentry initialization. There are several options you can pass to the integration constructor. See the configuration documentation for more details.

Several options are supported and passable using the integration constructor. See the configuration documentation for more details. To set up the integration, add the following to your Sentry initialization:

import * as Sentry from "@sentry/capacitor";
import { Replay } from "@sentry/replay";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // This sets the sample rate at 10%. You may want this to be 100% while
  // in development, then sample at a lower rate in production.
  replaysSessionSampleRate: 0.1,

  // If the entire session is not sampled, use the below sample rate to sample
  // sessions when an error occurs.
  replaysOnErrorSampleRate: 1.0,

  integrations: [
    replayIntegration({
      // Additional SDK configuration goes in here, for example:
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
});

Verify

While you're testing, we recommend that you set replaysSessionSampleRate to 1.0. This ensures that every user session will be sent to Sentry.

Once testing is complete, we recommend lowering this value in production. We still recommend keeping replaysOnErrorSampleRate set to 1.0, so that, whenever possible, every error has an associated replay with additional debugging context.

PII & Privacy Considerations

Personally identifiable information (PII) and privacy are important considerations when enabling Session Replay. There are multiple ways in which Sentry helps you avoid collecting PII, including:

• Masking, which replaces the text content with something else -- the default behavior being to replace each character with a *.
• Making network request, response bodies, and headers an opt-in feature, because the best way to avoid getting PII into Sentry is by not adding URLs of endpoints that may contain PII.

While we have certain privacy considerations in place, Sentry's Session Replay allows you to set up the privacy configurations that work best for your use case. For example, if you're working on a static website that's free of PII or other types of private data, you can opt out of the default text masking and image blocking settings. To learn more about Session Replay privacy, read our docs.

Content Security Policy (CSP)

worker-src 'self' blob:
child-src 'self' blob:

If you're unable to update your CSP policy to allow inline web workers, you can also use a custom compression worker instead.

User Session

A user session starts when the Session Replay SDK is first loaded and initialized. The session will capture any pageloads, refreshes, or navigations as long as the SDK is re-initialized on the same domain, and in the same browser tab, each time. Sessions continue capturing data until 5 minutes pass without any user interactions or until a maximum of 60 minutes have elapsed. Closing the browser tab will end the session immediately, according to the rules for SessionStorage.

Replay Captures on Errors Only

If you prefer not to record an entire session, you can elect to capture a replay only if an error occurs. In this case, the integration will buffer up to one minute worth of events prior to the error being thrown. It will continue to record the session, following the rules above regarding session life and activity. Read the sampling section for configuration options.

Sampling

Sampling controls how much traffic results in a Session Replay.

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // Capture 10% of all sessions
  replaysSessionSampleRate: 0.1,

  // Capture 100% of sessions with errors
  replaysOnErrorSampleRate: 1.0,

  integrations: [Sentry.replayIntegration()],
});

How Sampling Works

Sampling begins as soon as a session starts. When someone visits your application, sampling decisions happen in this order:

1. replaysSessionSampleRate is checked first

   • If sampled: Full session recording starts and is sent to Sentry in real-time
   • If not sampled: Recording is buffered in memory only (last 60 seconds kept)

2. If an error occurs (and session wasn't selected for full recording):

   • replaysOnErrorSampleRate is checked
   • If sampled: Buffered 60 seconds + rest of session is sent to Sentry
   • If not sampled: Buffer is discarded, nothing sent

When data leaves your browser:

Read more about understanding sessions.

Error Linking

Errors that happen on the page while a replay is running will be linked to the replay, making it possible to jump between related issues and replays. However, it's possible that in some cases the error count reported on the Replays Details page won't match the actual errors that have been captured. That's because errors can be lost, and while this is uncommon, there are a few reasons why it could happen:

• The replay was rate-limited and couldn't be accepted.
• The replay was deleted by a member of your org.
• There were network errors and the replay wasn't saved.

Trace Linking

When tracing is enabled, traces are visible in the Replay timeline. This lets you see performance data in the context of what the user was doing — you can watch a user click a button, then see the corresponding network request and how long it took.

From the Replay Details page, click on any trace span in the timeline to jump directly to the trace view. From there, you can drill into individual spans, see database queries, API calls, and identify performance bottlenecks that affected the user's experience.

This connection works both ways: when viewing a trace, you can jump to the associated replay to see exactly what the user experienced during that operation.

Verify

While you're testing, we recommend that you set replaysSessionSampleRate to 1.0. This ensures that every user session will be sent to Sentry.

Once testing is complete, we recommend lowering this value in production. We still recommend keeping replaysOnErrorSampleRate set to 1.0.

Related Features

• Tracing — Traces are visible in the Replay timeline, showing you performance data in context.
• Logs — Logs emitted during a replay session are automatically linked for easy navigation.

Replay Next Steps