/sentry-react-native-sdk

Session Replay — Sentry React Native SDK

Minimum SDK: @sentry/react-native ≥ 6.5.0
Status: Generally Available on all Sentry plans
Key difference from web: Screenshot-based capture, NOT DOM recording

How Mobile Replay Differs from Web Replay

Mobile Session Replay is fundamentally different from web replay. Understanding this distinction prevents surprises:

Mobile replay captures native view hierarchy snapshots + a screenshot within the same frame, compresses them into video segments, and streams them to Sentry alongside trace IDs, breadcrumbs, and debug info.

Minimum SDK Versions

Installation

No separate package needed — mobileReplayIntegration() is bundled in @sentry/react-native:

npm install @sentry/react-native
# or
yarn add @sentry/react-native

Android bundle size note: The replay module adds ~40 KB compressed / ~80 KB uncompressed. To exclude it entirely if you don't use replay:

// android/build.gradle (root level)
subprojects {
  configurations.all {
    exclude group: 'io.sentry', module: 'sentry-android-replay'
  }
}

Basic Setup

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "YOUR_DSN_HERE",

  // Session sampling — set both for comprehensive coverage
  replaysSessionSampleRate: 0.1,   // 10% of ALL sessions recorded immediately
  replaysOnErrorSampleRate: 1.0,   // 100% of sessions where an error occurs

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

During development: Use replaysSessionSampleRate: 1.0 so every session is recorded. Lower it in production while keeping replaysOnErrorSampleRate: 1.0.

Sample Rates

replaysSessionSampleRate

• Records the entire user session starting from SDK initialization / app foreground entry
• Range: 0.0 – 1.0
• Not supported in offline mode

replaysOnErrorSampleRate

• Only activates when an error occurs
• SDK maintains a rolling 1-minute pre-error buffer in memory
• Captures that buffer + everything after the error, giving you full context
• Range: 0.0 – 1.0
• ✅ Supported in offline mode — segments stored to disk, sent on reconnect

Recommended Production Values

Per-Error Filtering with beforeErrorSampling

Sentry.mobileReplayIntegration({
  beforeErrorSampling: (event, hint) => {
    // Only capture replays for UNHANDLED errors
    const isHandled = event.exception?.values?.some(
      (exception) => exception.mechanism?.handled === true,
    );
    return !isHandled; // returning false skips replay capture for this error
  },
})

All Configuration Options

mobileReplayIntegration() Options

Top-Level Sentry.init() Options

Privacy & Masking

⚠️ Production warning: Always verify your masking config before enabling in production. Default settings aggressively mask everything, but any modifications require thorough testing with your actual app UI. If you discover unmasked PII, open a GitHub issue and disable Session Replay until resolved.

Default Behavior

The SDK masks all text, images, vectors, webviews, and user input by default. Masked areas are replaced with a filled block using the most predominant color of the masked element.

Disable All Masking

Use only if your app contains absolutely no sensitive data:

Sentry.mobileReplayIntegration({
  maskAllText: false,
  maskAllImages: false,
  maskAllVectors: false,
})

Requires SDK 5.36.0 / 6.3.0+. If using manually initialized native SDKs, requires 6.15.1+ (Cocoa 8.52.1+).

Sentry.Mask and Sentry.Unmask Components

Requires SDK 6.4.0-beta.1+. These are React Native components for fine-grained, per-screen masking control:

import * as Sentry from "@sentry/react-native";

const ProfileScreen = () => (
  <View>
    {/* Unmask non-sensitive sections to see them clearly in replay */}
    <Sentry.Unmask>
      <Text>Welcome back!</Text>             {/* ✅ visible in replay */}
      <Text>Public username: johndoe</Text>  {/* ✅ visible in replay */}
    </Sentry.Unmask>

    {/* Mask sensitive sections regardless of global config */}
    <Sentry.Mask>
      <Text>Credit card: 4111-****-****-1111</Text>  {/* 🔒 masked */}
      <TextInput value={ssn} />                       {/* 🔒 masked */}
    </Sentry.Mask>
  </View>
);

Masking Rules & Priority

Sentry.Unmask only unmasks direct children:

<Sentry.Unmask>
  <Text>
    Unmasked line                {/* ✅ direct child — visible */}
    <Text>Nested text</Text>     {/* 🔒 indirect child — still masked */}
  </Text>
  <Text>Also unmasked</Text>    {/* ✅ direct child — visible */}
</Sentry.Unmask>

Sentry.Mask masks ALL descendants:

<Sentry.Mask>
  <Text>
    Masked                      {/* 🔒 */}
    <Text>Also masked</Text>    {/* 🔒 */}
  </Text>
</Sentry.Mask>

Mask always wins — Unmask cannot override it:

{/* Unmask inside Mask — Mask still wins */}
<Sentry.Mask>
  <Sentry.Unmask>
    <Text>Still masked</Text>   {/* 🔒 Unmask has no effect inside Mask */}
  </Sentry.Unmask>
</Sentry.Mask>

{/* Mask inside Unmask — Mask still takes effect */}
<Sentry.Unmask>
  <Sentry.Mask>
    <Text>Masked</Text>         {/* 🔒 */}
  </Sentry.Mask>
</Sentry.Unmask>

Implementation Notes

• Mask and Unmask are native components on both iOS and Android
• Compatible with both New Architecture and Legacy Architecture
• They behave as standard React Native View components (passthrough layout)

React Native View Flattening — Critical Privacy Gotcha

React Native's View Flattening optimization removes "Layout Only" views from the native hierarchy — and this includes your Mask/Unmask wrappers.

⚠️ View Flattening may cause Mask/Unmask to not work as expected, accidentally exposing sensitive data. Always test masking thoroughly on physical devices before shipping.

Diagnosis: If Sentry.Unmask isn't unmasking content more than one level deep, check whether the wrapper appears in the actual native view hierarchy (use the React Native Inspector or Xcode View Hierarchy Debugger). If the wrapper is absent, it's been flattened away.

Mitigation: Add collapsable={false} to prevent flattening of critical mask wrappers:

<Sentry.Mask collapsable={false}>
  <Text>Sensitive content</Text>
</Sentry.Mask>

Android: Screenshot Strategies

Requires SDK 7.5.0+. Configured via screenshotStrategy:

Sentry.mobileReplayIntegration({
  screenshotStrategy: "canvas",   // or "pixelCopy" (default)
})

Canvas caveat: When screenshotStrategy: "canvas" is set, maskAllText, maskAllImages, maskAllVectors, and Sentry.Unmask are all ignored. Everything is always fully masked — no selective unmasking is possible.

iOS: View Hierarchy Traversal

On iOS, the SDK traverses the native view hierarchy to capture screenshots. Some custom or third-party view classes can cause crashes or artifacts during traversal. Use these options (SDK 7.9.0+) to control which classes are included:

Sentry.mobileReplayIntegration({
  // Only traverse these specific native classes
  includedViewClasses: ["UILabel", "UIView", "MyCustomView"],

  // Never traverse these (even if listed in includedViewClasses)
  excludedViewClasses: ["WKWebView", "UIWebView", "ThirdPartyVideoView"],
})

Priority: excludedViewClasses always wins over includedViewClasses. Use excludedViewClasses to exclude problematic classes one at a time rather than rebuilding a full allowlist.

iOS 26.0 / Liquid Glass — Critical Warning

🚨 Potential PII leak on iOS 26.0+

Apple's Liquid Glass rendering in iOS 26.0 introduces masking vulnerabilities — masked areas may be rendered through the glass effect, potentially revealing content that should be hidden. Thoroughly test Session Replay on iOS 26+ before enabling in production. Track the fix at sentry-cocoa #6390.

Touch / Gesture Recording

Touch interactions are recorded as breadcrumb events (discrete tap events), not raw gesture streams. The replay UI overlays touch indicators at tap locations.

• What's captured: Tap position, tapped view, timestamp
• What's NOT captured: Swipe paths, gesture velocity, multi-touch sequences, pressure
• Display: Touch indicators overlaid on the replay video at breadcrumb timestamps

Network Request Capture

Network requests are automatically captured and displayed in the replay Network panel — no extra configuration needed.

Network capture works via existing Sentry network instrumentation, not replay-specific config. Unlike web replay, there is no way to opt in to body capture for mobile.

What the Replay UI Shows

Performance Overhead

Performance benchmarks on real production apps (Pocket Casts, release builds, 10 iterations).

iOS (iPhone 14 Pro)

Android (Pixel 2XL)

⚠️ Older devices (iPhone 8 and earlier): Replay can cause visible scrolling stutter and dropped frames during UI animations. Test on your minimum supported device before enabling.

Reducing Performance Impact

Sentry.init({
  replaysSessionSampleRate: 0.05,   // Lower session recording rate
  replaysSessionQuality: "low",     // ← Key setting for performance
  replaysOnErrorSampleRate: 1.0,    // Keep error capture at 100%
  integrations: [Sentry.mobileReplayIntegration()],
});

replaysSessionQuality options:

• 'low' — Lower CPU, memory, and bandwidth; reduced screenshot fidelity
• 'medium' (default) — Balanced
• 'high' — Best fidelity; highest resource usage

Session Lifecycle

Offline Support

Error Coverage

Session Replay links replays to all error types:

• ✅ Handled exceptions
• ✅ Unhandled exceptions
• ✅ ANRs (App Not Responding) / App Hangs
• ✅ Native (NDK) crashes

Expo Compatibility

mobileReplayIntegration() uses native modules for screenshot capture and the Mask/Unmask components.

For managed Expo workflow, use expo-dev-client or EAS Build — not Expo Go.

Metro Config — Component Names in Replay UI

Enable human-readable React component names in the replay UI (shows <ProfileCard> instead of <View>):

// metro.config.js
const { getDefaultConfig } = require("@react-native/metro-config");
const { withSentryConfig } = require("@sentry/react-native/metro");

module.exports = withSentryConfig(getDefaultConfig(__dirname), {
  annotateReactComponents: true,
});

This works with Hermes builds. The annotation happens at the native layer, not the JS thread.

Known Limitations vs. Web Replay

Production-Ready Setup Example

// App entry point (App.tsx / _layout.tsx)
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "YOUR_DSN_HERE",

  // Replay sampling
  replaysSessionSampleRate: 0.05,     // 5% of all sessions
  replaysOnErrorSampleRate: 1.0,      // 100% of error sessions
  replaysSessionQuality: "medium",    // 'low' | 'medium' | 'high'

  integrations: [
    Sentry.mobileReplayIntegration({
      // Privacy — defaults shown explicitly for clarity
      maskAllText: true,
      maskAllImages: true,
      maskAllVectors: true,

      // Android screenshot strategy (SDK 7.5.0+)
      screenshotStrategy: "pixelCopy",  // or 'canvas' (experimental, always masks)

      // iOS view traversal safety (SDK 7.9.0+)
      excludedViewClasses: ["WKWebView", "UIWebView"],

      // Selective replay — only for unhandled errors
      beforeErrorSampling: (event, hint) => {
        const isHandled = event.exception?.values?.some(
          (exc) => exc.mechanism?.handled === true,
        );
        return !isHandled;
      },
    }),
  ],
});

// Fine-grained masking in screens
import * as Sentry from "@sentry/react-native";

const PaymentScreen = () => (
  <View>
    {/* Unmask non-sensitive summary info */}
    <Sentry.Unmask>
      <Text>Order Summary</Text>
      <Text>Total: $42.00</Text>
    </Sentry.Unmask>

    {/* Always mask payment details */}
    <Sentry.Mask>
      <TextInput placeholder="Card number" />
      <TextInput placeholder="CVV" />
      <Text>Billing address...</Text>
    </Sentry.Mask>
  </View>
);

// metro.config.js — human-readable component names in replay UI
const { getDefaultConfig } = require("@react-native/metro-config");
const { withSentryConfig } = require("@sentry/react-native/metro");

module.exports = withSentryConfig(getDefaultConfig(__dirname), {
  annotateReactComponents: true,
});

Quick Reference

Minimum RN SDK:        6.5.0
Recording method:      Screenshots (~1 fps), NOT DOM recording
Pre-error buffer:      60 seconds
Session timeout:       30s background / 60 min max
Offline support:       Error mode only
Default masking:       ALL text, images, vectors, webviews — fully masked
Unmask scope:          Direct children only (not descendants)
Mask priority:         Always wins — Unmask cannot override
View flattening:       Can silently remove Mask/Unmask — test thoroughly!
Android strategies:    pixelCopy (default) | canvas (experimental, always-masks)
iOS view safety:       excludedViewClasses / includedViewClasses (SDK 7.9.0+)
iOS 26 warning:        Liquid Glass masking bug — test before production!
Component names:       metro.config.js → annotateReactComponents: true
Quality setting:       low | medium (default) | high
Expo Go:               ❌ Not supported — use expo-dev-client or EAS Build

Troubleshooting