Official React Native turbo module for Mixpanel Session Replay. Capture and analyze user interactions in your mobile app by bridging Mixpanel's native iOS and Android session replay SDKs to React Native.
- 🎥 Session Recording - Capture user interactions and screen recordings
- 🔒 Privacy First - Built-in data masking for sensitive information
- ⚡ High Performance - Native implementation with minimal JavaScript overhead
- 🎯 Selective Recording - Configurable sampling rates and recording controls
- 📱 Cross Platform - Unified API for both iOS and Android
- 🏗️ Dual Architecture Support - Works with both old (Bridge) and new (Turbo Module) React Native architectures
npm install @mixpanel/react-native-session-replayor
yarn add @mixpanel/react-native-session-replayThe SDK dependencies are automatically added via CocoaPods. Your project must target iOS 13 or later.
cd ios && pod installDependencies are automatically added through Gradle. Requirements:
- Minimum Android SDK 21+
- Kotlin support enabled
import {
MPSessionReplay,
MPSessionReplayConfig,
MPSessionReplayMask,
} from '@mixpanel/react-native-session-replay';
// Initialize session replay
const config = new MPSessionReplayConfig({
wifiOnly: false,
recordingSessionsPercent: 100,
autoStartRecording: true,
autoMaskedViews: [MPSessionReplayMask.Image, MPSessionReplayMask.Text],
flushInterval: 5,
enableLogging: true,
});
await MPSessionReplay.initialize(token, distinctId, config).catch((error) => {
console.error('Initialization error:', error);
});
// Control recording
await MPSessionReplay.startRecording();
await MPSessionReplay.stopRecording();
// Check recording status
const recording = await MPSessionReplay.isRecording();class MPSessionReplayConfig {
wifiOnly: boolean; // Only transmit on WiFi (default: true)
recordingSessionsPercent: number; // Sampling rate 0-100 (default: 100)
autoMaskedViews: MPSessionReplayMask[]; // Views to auto-mask (default: all)
autoStartRecording: boolean; // Start recording automatically (default: true)
flushInterval: number; // Flush interval in seconds (default: 10)
enableLogging: boolean; // Enable verbose logging (default: false)
}Controls whether replay events are sent only over WiFi.
- true - Events are flushed only when connected to WiFi. Without WiFi, events are queued in memory and will be lost if the app is killed before WiFi becomes available.
- false - Events are flushed over any network connection, including cellular.
- Default:
true
Sets the sampling rate for automatic session recording.
Accepts values from 0 to 100, representing the percentage of sessions that will automatically start recording.
- 0 - No automatic recording
- 100 - Record all sessions
- Default:
100 - Note: This only applies to automatic recording. Manual calls to
startRecording()are not affected.
Specifies which view types are automatically masked by the SDK.
By default, the SDK masks image, text, web, and map views (iOS only). You can customize this behavior through configuration.
Determines whether recording starts automatically on initialization.
- true - Recording starts automatically when initialized. The SDK stops and restarts recording as the app moves between background and foreground. Each new session uses
recordingSessionsPercentto determine if recording should begin. - false - Recording only starts when you explicitly call
startRecording(). - Default:
true
Sets how often screenshots are sent to Mixpanel, in seconds.
Screenshots are collected in batches of 10 and sent after each flush interval. Adjust this value to control how quickly screenshots are uploaded.
- Default:
10seconds
Enables debug logging for development and troubleshooting.
- true - Prints verbose debug logs including internal events, configuration status etc...
- false - No logs from the Session Replay SDK will be printed.
- Default:
false
MPSessionReplay.initialize(token: string, distinctId: string, config: MPSessionReplayConfig): Promise
Initializes the session replay system with your configuration. Checks remote settings to confirm recording is enabled, then creates a new session replay instance. Any existing instance is deinitialized first.
Returns: Promise that resolves when initialization completes successfully.
Throws: Error if initialization fails.
Manually starts session recording. Has no effect if recording is already active.
Recording continues until you stop it manually or the app moves to the background.
Stops the current recording session and performs cleanup.
Returns whether recording is currently active.
Updates the distinct ID for session replays after initialization.
Best practice: Call identify() on the main Mixpanel SDK first, then call it on the Session Replay SDK. This ensures users are properly merged.
The SDK automatically masks sensitive information to protect user privacy. Text input fields are always masked and cannot be disabled.
Session Replay provides two approaches to protect sensitive data: automatic masking and manual masking.
Configure which view types are automatically masked during initialization:
- Images
- Text elements
- WebView content
- Apple Maps (iOS only)
import { MPSessionReplayConfig } from '@mixpanel/react-native-session-replay';
const config = new MPSessionReplayConfig({
autoMaskedViews: [
MPSessionReplayMask.Text, // Masks all text
MPSessionReplayMask.Image, // Masks all images
MPSessionReplayMask.Web, // Masks all WebViews
MPSessionReplayMask.Map, // Masks map views (iOS only)
],
});Default Behavior: All view types are masked by default for maximum privacy.
Use the MPSessionReplayView wrapper component for granular control over what gets masked:
import { MPSessionReplayView } from '@mixpanel/react-native-session-replay';
// Mask sensitive content
<MPSessionReplayView sensitive={true}>
<Text>Credit card Number: {ccn}</Text>
<Text>Social Security Number: {ssn}</Text>
</MPSessionReplayView>
// Explicitly mark content as safe (unmasked)
<MPSessionReplayView sensitive={false}>
<Text>Public information that should always be visible</Text>
</MPSessionReplayView>Test the integration using the example app:
# Install dependencies
yarn
# Start Metro bundler
yarn example start
# Run on iOS
yarn example ios
# Run on Android
yarn example android- React Native 0.70 or higher
- iOS 13.0 or higher
- Android API Level 21 or higher
This module supports both the old and new React Native architectures:
- ✅ Old Architecture (Bridge) - Full support for traditional React Native apps
- ✅ New Architecture (Turbo Module) - Optimized for React Native's new architecture
The module automatically detects and uses the appropriate architecture at runtime, providing seamless compatibility regardless of your app's configuration.
See our contributing guide to learn how to contribute and understand the development workflow.
MIT