DocsTracking MethodsSDKsReact NativeSession Replay (React Native)

React Native Session Replay

Mixpanel’s React Native Session Replay SDK enables you to capture and analyze user interactions in your mobile applications. Built as a Turbo Module for React Native’s New Architecture, it provides native implementations for both iOS and Android with a unified JavaScript API.

Features

  • 📱 Cross-Platform Support - Unified API for iOS and Android
  • 🎥 Session Recording - Capture user interactions and screen recordings
  • 🔒 Privacy-First - Built-in data masking for sensitive information
  • ⚡ High Performance - Native implementation with minimal JavaScript bridge overhead
  • 🎯 Selective Recording - Configurable sampling rates and recording controls
  • 🚀 New Architecture Ready - Built as a Turbo Module with full type safety
  • 🛡️ Granular Privacy Controls - Auto-masking and manual masking via wrapper components

Requirements

  • React Native >= 0.70
  • iOS >= 13.0
  • Android API Level >= 21
  • New Architecture support (backward compatible with old architecture)

Installation

npm install @mixpanel/react-native-session-replay

or

yarn add @mixpanel/react-native-session-replay

Platform Setup

iOS

The SDK dependencies are automatically added via CocoaPods. Your project must target iOS 13 or later.

cd ios && pod install

Android

Dependencies are automatically added through Gradle. Requirements:

  • Minimum Android SDK 21+
  • Kotlin support enabled

Quick Start

Here’s a minimal example to get started with Session Replay:

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();

Configuration

The MPSessionReplayConfig class provides comprehensive control over session replay behavior:

const config = new MPSessionReplayConfig({
  wifiOnly: boolean,                // Default: true
  autoStartRecording: boolean,      // Default: true
  recordingSessionsPercent: number, // Default: 100 (range: 0-100)
  autoMaskedViews: MPSessionReplayMask[], // Default: all types
  flushInterval: number,            // Default: 10 (seconds)
  enableLogging: boolean,           // Default: false
});

Configuration Options

OptionTypeDefaultDescription
wifiOnlybooleantrueOnly transmit recordings over WiFi
autoStartRecordingbooleantrueAutomatically start recording on initialization
recordingSessionsPercentnumber100Percentage of sessions to record (0-100)
autoMaskedViewsMPSessionReplayMask[]All typesView types to automatically mask
flushIntervalnumber10Interval in seconds to flush recordings
enableLoggingbooleanfalseEnable debug logging

Auto-Masked View Types

The MPSessionReplayMask enum defines view types that can be automatically masked:

enum MPSessionReplayMask {
  Text = "text", // Text inputs and labels
  Web = "web", // WebView content
  Map = "map", // Map views (iOS only)
  Image = "image", // Image components
}

Example - Custom Auto-Masking:

import {
  MPSessionReplayConfig,
  MPSessionReplayMask,
} from "mixpanel-react-native-session-replay";
 
// Only mask text inputs and images
const config = new MPSessionReplayConfig({
  autoMaskedViews: [MPSessionReplayMask.Text, MPSessionReplayMask.Image],
});

API Reference

initialize

Initialize the Session Replay SDK with your configuration.

initialize(
  token: string,
  distinctId: string,
  config: MPSessionReplayConfig
): Promise<void>

Parameters:

  • token (required) - Your Mixpanel project token
  • distinctId (required) - User identifier for the session
  • config (required) - Session replay configuration

Validation:

  • Token must be a non-empty string
  • distinctId must be a non-empty string
  • recordingSessionsPercent must be between 0 and 100

Example:

const config = new MPSessionReplayConfig({
  autoStartRecording: true,
  enableLogging: __DEV__, // Enable logging in development
});
 
try {
  await MPSessionReplay.initialize("YOUR_TOKEN", "user-123", config);
  console.log("Session Replay initialized");
} catch (error) {
  console.error("Failed to initialize:", error);
}

startRecording

Start recording user interactions.

startRecording(): Promise<void>

Example:

await MPSessionReplay.startRecording();

stopRecording

Stop recording user interactions.

stopRecording(): Promise<void>

Example:

await MPSessionReplay.stopRecording();

isRecording

Check if session recording is currently active.

isRecording(): Promise<boolean>

Returns: Boolean indicating recording status

Example:

const recording = await MPSessionReplay.isRecording();
if (recording) {
  console.log("Session is being recorded");
}

identify

Update the user identifier for the current recording session.

identify(distinctId: string): Promise<void>

Parameters:

  • distinctId (required) - New user identifier

Example:

// Update user ID after authentication
await MPSessionReplay.identify("authenticated-user-456");

Privacy & Data Masking

Session Replay provides two approaches to protect sensitive data: automatic masking and manual masking.

Automatic Masking

Configure which view types are automatically masked during initialization:

const config = new MPSessionReplayConfig({
  autoMaskedViews: [
    MPSessionReplayMask.Text, // Masks all text inputs
    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.

Manual Masking with MPSessionReplayView

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}>
  <TextInput
    value={password}
    onChangeText={setPassword}
    secureTextEntry
  />
  <Text>Social Security Number: {ssn}</Text>
</MPSessionReplayView>
 
// Explicitly mark content as safe (not masked)
<MPSessionReplayView sensitive={false}>
  <Text>Public information that should always be visible</Text>
</MPSessionReplayView>

Complete Masking Example

import React, { useState } from "react";
import { View, TextInput, Image, Text } from "react-native";
import { MPSessionReplayView } from "mixpanel-react-native-session-replay";
import { WebView } from "react-native-webview";
 
function ProfileScreen() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
 
  return (
    <View>
      {/* Public information - not masked */}
      <Text>Welcome to Your Profile</Text>
 
      {/* Sensitive user data - masked */}
      <MPSessionReplayView sensitive={true}>
        <View>
          <Text>Email: {email}</Text>
          <TextInput
            value={email}
            onChangeText={setEmail}
            placeholder="email@example.com"
          />
 
          <Text>Password:</Text>
          <TextInput
            value={password}
            onChangeText={setPassword}
            secureTextEntry
          />
 
          <Image source={{ uri: profilePhotoUrl }} />
        </View>
      </MPSessionReplayView>
 
      {/* WebView masked by default if Web type is in autoMaskedViews */}
      <WebView source={{ uri: "https://example.com/terms" }} />
    </View>
  );
}
React NativeAndroid

Was this page useful?