@mixpanel/react-native-session-replay 1.3.0 → 1.4.0

package/MixpanelReactNativeSessionReplay.podspec

@@ -15,7 +15,7 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,cpp,swift}"
   s.private_header_files = "ios/**/*.h"
-  s.dependency 'MixpanelSessionReplay', '1.5.1'
+  s.dependency 'MixpanelSessionReplay', '1.6.0'
 # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
 # See https://github.com/facebook/react-native/blob/febf6b7f33fdb4904669f99d795eba4c0f95d7bf/scripts/cocoapods/new_architecture.rb#L79.
 if respond_to?(:install_modules_dependencies, true)

package/README.md

@@ -1,6 +1,6 @@
 # Mixpanel React Native Session Replay
 
-##### _June 10, 2026_ - [v1.3.0](https://github.com/mixpanel/mixpanel-react-native-session-replay/releases/tag/v1.3.0)
+##### _September 17, 2026_ - [v1.4.0](https://github.com/mixpanel/mixpanel-react-native-session-replay/releases/tag/v1.4.0)
 
 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.
 

package/android/build.gradle

@@ -17,7 +17,13 @@ buildscript {
 
 
 apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
+// AGP 9 ships built-in Kotlin support and registers the `kotlin` extension
+// itself. Applying the Kotlin plugin on top of it fails configuration with
+// "Cannot add extension with name 'kotlin'". Only apply it when nothing has
+// registered that extension yet.
+if (project.extensions.findByName('kotlin') == null) {
+  apply plugin: "kotlin-android"
+}
 
 apply plugin: "com.facebook.react"
 
@@ -78,8 +84,9 @@ dependencies {
   // Mixpanel Android SDK dependency (minimum v8.0.2)
   implementation "com.mixpanel.android:mixpanel-android:8.0.2"
   
-  // Mixpanel Android Session Replay SDK dependency
-  implementation "com.mixpanel.android:mixpanel-android-session-replay:1.4.0"
+  implementation "com.mixpanel.android:mixpanel-android-session-replay:1.5.0"
+
+  testImplementation "junit:junit:4.13.2"
 }
 
 react {

package/android/src/main/java/com/mixpanelreactnativesessionreplay/MixpanelReactNativeSessionReplayModule.kt

@@ -7,9 +7,11 @@ import com.facebook.react.module.annotations.ReactModule
 import com.mixpanel.android.sessionreplay.MPSessionReplay
 import com.mixpanel.android.sessionreplay.MPSessionReplayInstance
 import com.mixpanel.android.sessionreplay.MPSessionReplayError
+import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.mixpanel.android.sessionreplay.models.MPSessionReplayConfig
 import com.mixpanel.android.sessionreplay.sensitive_views.AutoMaskedView
 import com.mixpanel.android.sessionreplay.utils.APIConstants
+import com.mixpanel.android.sessionreplay.wireframe.WireframeDebugSnapshot
 import org.json.JSONObject
 import org.json.JSONArray
 
@@ -52,6 +54,18 @@ class MixpanelReactNativeSessionReplayModule(reactContext: ReactApplicationConte
       }
       println("Mixpanel - Config variable fromJson: $replayConfig")
 
+      // `emitWireframes` is this bridge's own debug switch, not SDK configuration: the SDK's
+      // `DebugOptions.wireframeEmitter` is a callback, which cannot cross as JSON, so JS sends a
+      // boolean alongside it and the bridge attaches the destination the config could not carry.
+      // The SDK deliberately does not model the flag, so read it from the payload.
+      val emitWireframes =
+        config.optJSONObject("debugOptions")?.optBoolean("emitWireframes") == true
+      if (emitWireframes) {
+        replayConfig.debugOptions?.let { debugOptions ->
+          replayConfig.debugOptions = debugOptions.copy(wireframeEmitter = ::emitWireframeSnapshot)
+        }
+      }
+
       // Set library version and name
       APIConstants.setLibVersion(LIB_VERSION)
       APIConstants.setMpLib(MP_LIB)
@@ -70,6 +84,9 @@ class MixpanelReactNativeSessionReplayModule(reactContext: ReactApplicationConte
               try {
                 // Configure AutoMaskedView categories with comprehensive React Native support
                 configureSensitiveClasses(instance, replayConfig)
+                // Android clears its native declaration registry during reinitialization. React
+                // does not resend unchanged props, so restore declarations cached by mounted views.
+                WireframeTextDeclarationRegistry.reapplyAll()
                 println("Mixpanel - Session Replay initialized successfully with enhanced view masking")
                 promise.resolve(null)
               } catch (e: Exception) {
@@ -176,6 +193,40 @@ class MixpanelReactNativeSessionReplayModule(reactContext: ReactApplicationConte
     }
   }
 
+  /**
+   * Forwards one captured wireframe to JavaScript as JSON.
+   *
+   * The snapshot crosses as a string rather than a `WritableMap` because
+   * [WireframeDebugSnapshot.toJson] already exists and is the same shape iOS sends —
+   * building a map here would make the bridge a third place the shape could drift.
+   *
+   * Called on the SDK's debug scope, off the main thread, once per captured frame.
+   * Delivery is best-effort: during teardown or a reload there is no JS runtime to emit
+   * into, and a debug aid must never take down the host app, so failures are logged and
+   * dropped.
+   */
+  private fun emitWireframeSnapshot(snapshot: WireframeDebugSnapshot) {
+    try {
+      if (!reactApplicationContext.hasActiveReactInstance()) return
+      reactApplicationContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(WIREFRAME_EVENT, snapshot.toJson())
+    } catch (e: Exception) {
+      println("Mixpanel - Failed to deliver wireframe snapshot to JS: ${e.message}")
+    }
+  }
+
+  /**
+   * Required by `NativeEventEmitter` on a TurboModule. No-ops here: events go out over
+   * [DeviceEventManagerModule.RCTDeviceEventEmitter], which broadcasts without per-listener
+   * registration. iOS inherits real implementations from `RCTEventEmitter`.
+   */
+  @ReactMethod
+  override fun addListener(eventName: String) = Unit
+
+  @ReactMethod
+  override fun removeListeners(count: Double) = Unit
+
   /**
    * Safely configure sensitive classes for comprehensive React Native view masking
    * Supports both old and new React Native architectures with crash prevention
@@ -309,5 +360,8 @@ class MixpanelReactNativeSessionReplayModule(reactContext: ReactApplicationConte
     const val NAME = "MixpanelReactNativeSessionReplay"
     const val LIB_VERSION = "1.2.0"
     const val MP_LIB = "react-native-sr"
+
+    /** Must match `WIREFRAME_EVENT` in `src/index.tsx` and `supportedEvents` on iOS. */
+    const val WIREFRAME_EVENT = "MixpanelSessionReplayWireframe"
   }
 }

package/android/src/main/java/com/mixpanelreactnativesessionreplay/MixpanelSessionReplayView.kt

@@ -3,9 +3,53 @@ package com.mixpanelreactnativesessionreplay
 import android.content.Context
 import com.facebook.react.views.view.ReactViewGroup
 import com.mixpanel.android.sessionreplay.MPSessionReplay
+import com.mixpanel.android.sessionreplay.extensions.mpWireframeText
+import java.util.Collections
+import java.util.WeakHashMap
+
+internal class WireframeTextDeclaration(
+    private val applyText: (String?) -> Unit,
+) {
+    private var text: String? = null
+
+    init {
+        WireframeTextDeclarationRegistry.register(this)
+    }
+
+    fun update(text: String?) {
+        if (this.text == text) return
+
+        this.text = text
+        applyText(text)
+    }
+
+    fun reapply() {
+        // A null value means the declaration is already absent from the freshly reset SDK registry.
+        text?.let(applyText)
+    }
+}
+
+internal object WireframeTextDeclarationRegistry {
+    private val declarations =
+        Collections.synchronizedMap(WeakHashMap<WireframeTextDeclaration, Unit>())
+
+    fun register(declaration: WireframeTextDeclaration) {
+        declarations[declaration] = Unit
+    }
+
+    fun reapplyAll() {
+        val snapshot = synchronized(declarations) { declarations.keys.toList() }
+        snapshot.forEach(WireframeTextDeclaration::reapply)
+    }
+
+    internal fun clearForTests() {
+        declarations.clear()
+    }
+}
 
 class MixpanelSessionReplayView(context: Context) : ReactViewGroup(context) {
     private var isSensitive: Boolean = false
+    private val wireframeTextDeclaration = WireframeTextDeclaration(::mpWireframeText)
 
     fun setSensitive(sensitive: Boolean) {
         if (isSensitive == sensitive) return
@@ -13,6 +57,18 @@ class MixpanelSessionReplayView(context: Context) : ReactViewGroup(context) {
         isSensitive = sensitive
         updateViewSensitivity()
     }
+
+    /**
+     * Declares the text recorded for this view in the `mp_wireframe` event.
+     *
+     * Orthogonal to [setSensitive] — this has no bearing on which pixels are captured,
+     * and masking has no bearing on the declared text. Unlike sensitivity, it needs no
+     * live [MPSessionReplay] instance: the declaration is held by the SDK's view manager,
+     * so a prop that arrives before `initialize` still applies.
+     */
+    fun setWireframeText(text: String?) {
+        wireframeTextDeclaration.update(text)
+    }
     
     private fun updateViewSensitivity() {
         MPSessionReplay.getInstance()?.let { sessionReplay ->

package/android/src/main/java/com/mixpanelreactnativesessionreplay/MixpanelSessionReplayViewManager.kt

@@ -26,4 +26,9 @@ class MixpanelSessionReplayViewManager : ViewGroupManager<MixpanelSessionReplayV
         println("MixpanelSessionReplayView - setSensitive called with value: $sensitive for view: $view")
         view.setSensitive(sensitive)
     }
+
+    @ReactProp(name = "wireframeText")
+    fun setWireframeText(view: MixpanelSessionReplayView, wireframeText: String?) {
+        view.setWireframeText(wireframeText)
+    }
 }

package/android/src/test/java/com/mixpanelreactnativesessionreplay/WireframeTextDeclarationTest.kt

@@ -0,0 +1,41 @@
+package com.mixpanelreactnativesessionreplay
+
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+
+class WireframeTextDeclarationTest {
+    @Before
+    fun setUp() {
+        WireframeTextDeclarationRegistry.clearForTests()
+    }
+
+    @After
+    fun tearDown() {
+        WireframeTextDeclarationRegistry.clearForTests()
+    }
+
+    @Test
+    fun `reapplies unchanged text after native registry reset`() {
+        val appliedValues = mutableListOf<String?>()
+        val declaration = WireframeTextDeclaration(appliedValues::add)
+
+        declaration.update("Checkout")
+        WireframeTextDeclarationRegistry.reapplyAll()
+
+        assertEquals(listOf("Checkout", "Checkout"), appliedValues)
+    }
+
+    @Test
+    fun `does not reapply a cleared declaration`() {
+        val appliedValues = mutableListOf<String?>()
+        val declaration = WireframeTextDeclaration(appliedValues::add)
+
+        declaration.update("Checkout")
+        declaration.update(null)
+        WireframeTextDeclarationRegistry.reapplyAll()
+
+        assertEquals(listOf("Checkout", null), appliedValues)
+    }
+}

package/ios/MixpanelReactNativeSessionReplay.h

@@ -1,13 +1,18 @@
+#import <React/RCTEventEmitter.h>
+
 #ifdef RCT_NEW_ARCH_ENABLED
 #import <MixpanelReactNativeSessionReplaySpec/MixpanelReactNativeSessionReplaySpec.h>
 #else
 #import <React/RCTBridgeModule.h>
 #endif
 
+// Subclasses `RCTEventEmitter` for the wireframe debug channel. That also supplies the
+// `addListener:`/`removeListeners:` the TurboModule spec now declares, so the protocol
+// conformance below is satisfied without implementing them here.
 #ifdef RCT_NEW_ARCH_ENABLED
-@interface MixpanelReactNativeSessionReplay : NSObject <NativeMixpanelReactNativeSessionReplaySpec>
+@interface MixpanelReactNativeSessionReplay : RCTEventEmitter <NativeMixpanelReactNativeSessionReplaySpec>
 #else
-@interface MixpanelReactNativeSessionReplay : NSObject <RCTBridgeModule>
+@interface MixpanelReactNativeSessionReplay : RCTEventEmitter <RCTBridgeModule>
 #endif
 
 @end

package/ios/MixpanelReactNativeSessionReplay.mm

@@ -5,9 +5,33 @@
   #import <MixpanelReactNativeSessionReplay/MixpanelReactNativeSessionReplay-Swift.h>
 #endif
 
-@implementation MixpanelReactNativeSessionReplay
+/// Must match `WIREFRAME_EVENT` in `src/index.tsx` and `WIREFRAME_EVENT` on Android.
+static NSString *const kMixpanelWireframeEvent = @"MixpanelSessionReplayWireframe";
+
+@implementation MixpanelReactNativeSessionReplay {
+  // Set between `startObserving` and `stopObserving`. `sendEventWithName:` logs a warning
+  // when nothing is listening, and wireframes fire once per captured frame, so an app that
+  // enabled the emitter and then removed its listener would otherwise flood the console.
+  BOOL _hasWireframeListeners;
+}
+
 RCT_EXPORT_MODULE()
 
+- (NSArray<NSString *> *)supportedEvents
+{
+  return @[ kMixpanelWireframeEvent ];
+}
+
+- (void)startObserving
+{
+  _hasWireframeListeners = YES;
+}
+
+- (void)stopObserving
+{
+  _hasWireframeListeners = NO;
+}
+
 RCT_EXPORT_METHOD(initialize:(nonnull NSString *)token distinctId:(nonnull NSString *)distinctId configJSON:(nonnull NSString *)configJSON resolve:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject)
 {
     @try {
@@ -15,7 +39,16 @@ RCT_EXPORT_METHOD(initialize:(nonnull NSString *)token distinctId:(nonnull NSStr
             reject(@"INVALID_CONFIG", @"Token and distinctId are required", nil);
             return;
         }
-      [MixpanelSwiftSessionReplay initialize:token distinctId:distinctId configJSON:configJSON completion:^(BOOL success, NSError * _Nullable error) {
+      // Weak, because the SDK holds this block for the process lifetime — the module must not
+      // be kept alive by it, and after a reload there may be no module to deliver to.
+      __weak MixpanelReactNativeSessionReplay *weakSelf = self;
+      [MixpanelSwiftSessionReplay initialize:token distinctId:distinctId configJSON:configJSON wireframeHandler:^(NSString *snapshotJSON) {
+        MixpanelReactNativeSessionReplay *strongSelf = weakSelf;
+        if (strongSelf == nil || !strongSelf->_hasWireframeListeners) {
+          return;
+        }
+        [strongSelf sendEventWithName:kMixpanelWireframeEvent body:snapshotJSON];
+      } completion:^(BOOL success, NSError * _Nullable error) {
         if (success) {
           resolve(nil);
         } else {

package/ios/MixpanelSessionReplayViewManager.mm

@@ -33,4 +33,13 @@ RCT_CUSTOM_VIEW_PROPERTY(sensitive, BOOL, RCTView)
   }
 }
 
+// Declares the text recorded for this view in the wireframe. Orthogonal to `sensitive`:
+// declared text is authored by the developer, so it ships even for a masked view. `nil`
+// clears the declaration, which is what a removed or emptied prop sends.
+RCT_CUSTOM_VIEW_PROPERTY(wireframeText, NSString *, RCTView)
+{
+  NSString *text = [json isKindOfClass:[NSString class]] ? (NSString *)json : nil;
+  [MixpanelSwiftSessionReplay setMPWireframeTextWithValue:text view:view];
+}
+
 @end

package/ios/MixpanelSwiftSessionReplay.swift

@@ -18,8 +18,13 @@ import UIKit
     MPSessionReplay.getInstance()?.captureScreenshot()
   }
 
+  /// - Parameter wireframeHandler: Destination for each captured wireframe's debug JSON.
+  ///   Attached only when the payload's `debugOptions.emitWireframes` is set — this bridge's own
+  ///   debug switch, read here rather than modelled by the SDK (see `BridgeDebugFlags`). Without
+  ///   it the SDK builds no snapshot at all, so an app that has not asked pays nothing.
   @objc public static func initialize(
     _ token: String, distinctId: String, configJSON: String,
+    wireframeHandler: ((String) -> Void)? = nil,
     completion: @escaping (Bool, NSError?) -> Void
   ) {
     guard let data = configJSON.data(using: .utf8) else {
@@ -31,7 +36,20 @@ import UIKit
     do {
       APIConstants.setLibVersion(libVersion)
       APIConstants.setMpLib(mpLib)
-      let config = try MPSessionReplayConfig.from(json: data)
+      var config = try MPSessionReplayConfig.from(json: data)
+
+      // `emitWireframes` is this bridge's switch, not SDK configuration; the SDK ignores the
+      // key and the bridge attaches the destination the config could not carry.
+      let emitWireframes =
+        (try? JSONDecoder().decode(BridgeDebugFlags.self, from: data))?
+        .debugOptions?.emitWireframes ?? false
+
+      if let wireframeHandler, emitWireframes {
+        config.debugOptions?.wireframeEmitter = { snapshot in
+          wireframeHandler(snapshot.toJson())
+        }
+      }
+
       MPSessionReplay.initialize(token: token, distinctId: distinctId, config: config) { result in
         switch result {
         case .success(_?):
@@ -86,6 +104,16 @@ import UIKit
     view.mpReplaySensitive = value
   }
 
+  /// Declares the text recorded for `view` in the wireframe.
+  ///
+  /// Orthogonal to `setMPReplaySensitive` — the declared text is sent even when the view
+  /// is masked, because it is authored by the developer rather than scraped from the
+  /// screen. Pass `nil` (or a blank string) to clear it.
+  @objc public static func setMPWireframeText(value: String?, view: UIView) {
+    let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines)
+    view.mpWireframeText = (trimmed?.isEmpty == false) ? trimmed : nil
+  }
+
   private static func createError(_ message: String, code: Int = -1) -> NSError {
     return NSError(
       domain: "MixpanelSessionReplay",
@@ -112,3 +140,17 @@ import UIKit
     }
   }
 }
+
+/// The one key JS sends inside `debugOptions` that the SDK does not model.
+///
+/// `emitWireframes` is a bridge-level debug switch rather than SDK configuration: the SDK's
+/// `DebugOptions.wireframeEmitter` is a closure and cannot cross the bridge as JSON, so JS sends
+/// a boolean and the bridge supplies the callback. Keeping the flag here rather than in the SDK's
+/// public `DebugOptions` leaves no inert knob on the native API surface.
+private struct BridgeDebugFlags: Decodable {
+  struct DebugSection: Decodable {
+    var emitWireframes: Bool?
+  }
+
+  var debugOptions: DebugSection?
+}

package/lib/module/MixpanelSessionReplayView.js.map

@@ -1 +1 @@
-{"version":3,"names":["requireNativeComponent","MPSessionReplayView"],"sourceRoot":"../../src","sources":["MixpanelSessionReplayView.tsx"],"mappings":";;AAAA,SAASA,sBAAsB,QAAwB,cAAc;AAMrE,OAAO,MAAMC,mBAAmB,GAC9BD,sBAAsB,CACpB,2BACF,CAAC","ignoreList":[]}
+{"version":3,"names":["requireNativeComponent","MPSessionReplayView"],"sourceRoot":"../../src","sources":["MixpanelSessionReplayView.tsx"],"mappings":";;AAAA,SAASA,sBAAsB,QAAwB,cAAc;AAuCrE,OAAO,MAAMC,mBAAmB,GAC9BD,sBAAsB,CACpB,2BACF,CAAC","ignoreList":[]}

package/lib/module/NativeMixpanelReactNativeSessionReplay.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativeModules","TurboModuleRegistry","isTurboModuleEnabled","global","__turboModuleProxy","MixpanelReactNativeSessionReplay","get","e","console","warn","errorMessage","Error"],"sourceRoot":"../../src","sources":["NativeMixpanelReactNativeSessionReplay.ts"],"mappings":";;AACA,SAASA,aAAa,EAAEC,mBAAmB,QAAQ,cAAc;;AAiBjE;;AAKA;AACA;AACA,MAAMC,oBAAoB,GAAGC,MAAM,CAACC,kBAAkB,IAAI,IAAI;AAE9D,IAAIC,gCAA6C,GAAG,IAAI;AAExD,IAAIH,oBAAoB,EAAE;EACxB;EACA,IAAI;IACFG,gCAAgC,GAAGJ,mBAAmB,CAACK,GAAG,CACxD,kCACF,CAAC;EACH,CAAC,CAAC,OAAOC,CAAC,EAAE;IACV;IACAC,OAAO,CAACC,IAAI,CACV,4FACF,CAAC;EACH;AACF;;AAEA;AACA,IAAI,CAACJ,gCAAgC,EAAE;EACrCA,gCAAgC,GAC9BL,aAAa,CAACK,gCAAgC;AAClD;;AAEA;AACA,IAAI,CAACA,gCAAgC,EAAE;EACrC,MAAMK,YAAY,GAChB,+FAA+F,GAC/F,mJAAmJ,GACnJ,4DAA4D,GAC5D,2GAA2G,GAC3G,sFAAsF,GACtF,yEAAyE;EAE3E,MAAM,IAAIC,KAAK,CAACD,YAAY,CAAC;AAC/B;AAEA,eAAeL,gCAAgC","ignoreList":[]}
+{"version":3,"names":["NativeModules","TurboModuleRegistry","isTurboModuleEnabled","global","__turboModuleProxy","MixpanelReactNativeSessionReplay","get","e","console","warn","errorMessage","Error"],"sourceRoot":"../../src","sources":["NativeMixpanelReactNativeSessionReplay.ts"],"mappings":";;AACA,SAASA,aAAa,EAAEC,mBAAmB,QAAQ,cAAc;;AAwBjE;;AAKA;AACA;AACA,MAAMC,oBAAoB,GAAGC,MAAM,CAACC,kBAAkB,IAAI,IAAI;AAE9D,IAAIC,gCAA6C,GAAG,IAAI;AAExD,IAAIH,oBAAoB,EAAE;EACxB;EACA,IAAI;IACFG,gCAAgC,GAAGJ,mBAAmB,CAACK,GAAG,CACxD,kCACF,CAAC;EACH,CAAC,CAAC,OAAOC,CAAC,EAAE;IACV;IACAC,OAAO,CAACC,IAAI,CACV,4FACF,CAAC;EACH;AACF;;AAEA;AACA,IAAI,CAACJ,gCAAgC,EAAE;EACrCA,gCAAgC,GAC9BL,aAAa,CAACK,gCAAgC;AAClD;;AAEA;AACA,IAAI,CAACA,gCAAgC,EAAE;EACrC,MAAMK,YAAY,GAChB,+FAA+F,GAC/F,mJAAmJ,GACnJ,4DAA4D,GAC5D,2GAA2G,GAC3G,sFAAsF,GACtF,yEAAyE;EAE3E,MAAM,IAAIC,KAAK,CAACD,YAAY,CAAC;AAC/B;AAEA,eAAeL,gCAAgC","ignoreList":[]}