Enable Session Replay on React Native

Overview

Follow this guide to enable Session Replay for Real User Monitoring (RUM) in your React Native app.

Session Replay captures a visual sequence of user interactions by recording periodic screenshots of your app. Analyze what the user saw before, during, and after an issue — helping you quickly pinpoint the source of errors, performance slowdowns, or unexpected behavior. Use Session Replay to recreate the user experience and better understand the context behind each session.

Recordings from React Native appear in the same Session Replay UI as other mobile sessions. The device context indicates that the source is a React Native app.

Prerequisites

Before enabling Session Replay, you must install and initialize the Coralogix React Native RUM SDK in your app using the @coralogix/react-native-plugin package.

Session Replay by default

After you enable Session Replay:

• The SDK captures screenshots periodically during the session.
• Sessions are recorded according to the configured sessionRecordingSampleRate.
• All on-screen text is masked when you keep the default maskAllTexts setting.
• Images are shown as-is unless you explicitly enable maskAllImages.

You can refine this behavior using the options described below.

Configure and initialize

Use the SessionReplay.init function to configure capture behavior, privacy masking, and sampling.

Example

import { SessionReplay } from '@coralogix/react-native-plugin';

await SessionReplay.init({
  captureScale: 0.5,                    // 0.0–1.0, lower values reduce image size
  captureCompressQuality: 0.8,          // 0.0–1.0, higher values improve quality
  sessionRecordingSampleRate: 100,      // 0–100, percentage of sessions to record
  autoStartSessionRecording: true,      // Start recording automatically after init
  maskAllTexts: true,                   // Mask all text content by default
  textsToMask: ['password', '^card.*'], // Used when maskAllTexts is false
  maskAllImages: false,                 // Mask all images when true
});

Always call SessionReplay.init after CoralogixRum.init and as early as possible in your app lifecycle, for example in your root component or bootstrap file.

Check initialization and recording status

Use these helpers to verify that Session Replay is correctly initialized and actively recording:

const isInited = await SessionReplay.isInited();
console.log('Session Replay initialized:', isInited);

const isRecording = await SessionReplay.isRecording();
console.log('Session Replay recording:', isRecording);

Options reference

Configuration fields for SessionReplay.init(options):

Option	Type	Description	Default
captureScale	number (0.0–1.0)	Screenshot resolution scale factor. Lower values reduce image size and bandwidth usage at the cost of visual detail	0.5
captureCompressQuality	number (0.0–1.0)	Image compression quality. Lower values reduce fidelity and file size; higher values improve clarity	1
sessionRecordingSampleRate	number (0–100)	Percentage of sessions to record. Use 100 to record all sessions	100%
autoStartSessionRecording	boolean	When true, recording starts automatically after initialization. When false, you must call startSessionRecording() manually	false
maskAllTexts	boolean	When true, all text content in captured views is masked. When false, only patterns in textsToMask are masked	true
textsToMask	string[]	Array of string or regex patterns used to mask specific text values. Only applied when maskAllTexts is false	null
maskAllImages	boolean	When true, all images in captured views are masked (for example, to hide screenshots that may contain sensitive data)	false

Recommended combinations:

• To mask everything by default: keep maskAllTexts = true and set maskAllImages = true.
• To show most text but hide specific values (such as passwords or card labels): set maskAllTexts = false and provide patterns in textsToMask.
• To show all content: set maskAllTexts = false, leave textsToMask empty, and keep maskAllImages = false. Only use this configuration in controlled environments where it is safe to display all text and images.

Image capture triggers

Screenshots are captured during session replay in the following cases:

• Periodically, based on the internal capture schedule configured via captureScale and captureCompressQuality.
• When the user interacts with the app (for example, tapping or navigating between screens).
• When notable events occur in the session, such as errors or crashes.
• When a manual capture is triggered via SessionReplay.captureScreenshot().

This hybrid approach helps ensure that important context is captured even between periodic screenshots.

Start and stop recording

If autoStartSessionRecording is false, or if you want finer control over when sessions are recorded, use the following methods to control recording manually:

import { SessionReplay } from '@coralogix/react-native-plugin';

// Start recording the current session
SessionReplay.startSessionRecording();

// Stop recording the current session
SessionReplay.stopSessionRecording();

You can use these controls to record only specific user flows (for example, a checkout funnel) instead of the entire app session.

Manually capture screen

Use captureScreenshot to manually capture a specific moment in the session, in addition to the automatic captures.

Example

import { SessionReplay } from '@coralogix/react-native-plugin';

// Capture a one-off screenshot at a key step in the flow
SessionReplay.captureScreenshot();

This is useful when you know a particular view or state is important to debug issues, and you want to guarantee that it appears in the replay.

Privacy and masking

Coralogix provides flexible masking options in the React Native plugin to help you meet privacy and compliance requirements:

• Global text masking
  • Use maskAllTexts: true (default) to redact all text content from captured views.
  • Use maskAllTexts: false together with textsToMask to mask only specific values such as "password" or patterns like "^card.*".
• Global image masking
  • Use maskAllImages: true to mask every image in captured screenshots. This is recommended when images may contain sensitive content (for example, uploaded documents or screenshots).

• View-level masking

  For fine-grained control, you can mask specific React Native views at layout time using SessionReplay.maskView:

  import { SessionReplay } from '@coralogix/react-native-plugin';
  import { View, Text, TextInput } from 'react-native';
  
  function PaymentForm() {
    return (
      <View onLayout={SessionReplay.maskView}>
        <Text>Card number</Text>
        <TextInput placeholder="1234 5678 9012 3456" />
      </View>
    );
  }
  

  Any view that calls SessionReplay.maskView via the onLayout prop will be masked in session replay recordings, while the rest of the screen remains visible according to your global masking configuration.