@mixpanel/react-native-session-replay
Advanced tools
Official React Native turbo module for Mixpanel Session Replay
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.
npm install @mixpanel/react-native-session-replay
or
yarn add @mixpanel/react-native-session-replay
The SDK dependencies are automatically added via CocoaPods. Your project must target iOS 15 or later.
cd ios && pod install
Swift Package Manager (React Native 0.88+, experimental). The package ships a Package.swift that React Native's SwiftPM autolinking picks up, so no extra configuration is needed. Opt your app into SwiftPM from its ios folder:
npx react-native spm --deintegrate
--deintegrate removes CocoaPods from the project, and npx react-native spm deinit reverses the change. After a fresh clone, and in CI, run npx react-native spm once before building, as you would pod install. React Native's SwiftPM support is still experimental; see the React Native 0.88 release notes for its current limitations.
The package pins the Session Replay iOS SDK to the exact version each release is tested with. If your app also depends on mixpanel-ios-session-replay-package directly, use the version in ios/Package.swift, or Swift Package Manager won't be able to resolve your packages.
Dependencies are automatically added through Gradle. Requirements:
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.
trueSets the sampling rate for automatic session recording.
Accepts values from 0 to 100, representing the percentage of sessions that will automatically start recording.
100startRecording() 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.
recordingSessionsPercent to determine if recording should begin.startRecording().trueSets 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.
10 secondsEnables debug logging for development and troubleshooting.
falseInitializes 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:
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
We add support for each new Xcode's minimum deployment target promptly after its release, and drop the previous minimum only when Apple's App Store SDK requirement forces it.
Version 2.x requires iOS 15.0+ and React Native 0.76+, and builds with Xcode 26 or Xcode 27. If you need to support older iOS versions, stay on 1.x and build with Xcode 26. 1.x receives security and critical fixes until Apple requires the iOS 27 SDK for App Store submissions (April 2027).
This module supports both the old and new React Native architectures:
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
FAQs
Official React Native turbo module for Mixpanel Session Replay
The npm package @mixpanel/react-native-session-replay receives a total of 44,771 weekly downloads. As such, @mixpanel/react-native-session-replay popularity was classified as popular.
We found that @mixpanel/react-native-session-replay demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 10 open source maintainers collaborating on the project.
Security News
GitHub is tightening GitHub Actions security with new restrictions on privileged pull request workflows. Here's what changes and how maintainers are affected.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.