# Enable session replay on React Native ## Overview Follow this guide to enable [Session Replay](https://coralogix.com/docs/user-guides/rum/product-features/session-replay/index.md) 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 RUM React Native Plugin](https://coralogix.com/docs/user-guides/rum/sdk-installation/react-native/react-native-plugin/index.md) in your app using the `@coralogix/react-native-plugin` package. Note Session Replay extends the React Native RUM plugin and must be initialized after `CoralogixRum.init()`. Attempting to initialize Session Replay before the base SDK is ready will result in an initialization error or no data being captured. ## 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](#options-reference) described below. ## Configure and initialize Use the `SessionReplay.init` function to configure capture behavior, privacy masking, and sampling. ### Example ```javascript 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: ```jsx 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` (greater than 0, up to 1.0) | Image compression quality. Lower values reduce fidelity and file size; higher values improve clarity. A value of `0` is invalid and rejected at init time | `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()`](#manually-capture-screen). 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: ```jsx 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. ## Shut down Session Replay Stop the recorder and release its resources. After shutdown, calling `startSessionRecording()` again has no effect until you re-initialize. ```jsx import { SessionReplay } from '@coralogix/react-native-plugin'; await SessionReplay.shutdown(); ``` ## Manually capture screen Use `captureScreenshot` to manually capture a specific moment in the session, in addition to the automatic captures. ### Example ```jsx 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`: ```jsx import { SessionReplay } from '@coralogix/react-native-plugin'; import { View, Text, TextInput } from 'react-native'; function PaymentForm() { return ( Card number ); } ``` 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. Tip Start with aggressive masking in staging (for example, `maskAllTexts` = `true` and `maskAllImages` = `true`), then gradually relax your settings as you verify that no sensitive content is exposed in the resulting replays.