@coralogix/react-native-plugin 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.11.0 (2026-08-31)
+
+### 🚀 Features
+
+- New `Masked` component masks its subtree in session replay and in the interaction metadata of every control inside it
+- Masking now applies to user-interaction events: a tap anywhere in a masked control reports its text as `***`, with both `Masked` and `SessionReplay.maskView`
+- Masked interactions report `interaction_context.is_masked_element`, readable in `beforeSend`
+- Scroll and swipe inside a masked container now report as masked
+- Taps on a `Text` with an `onPress` handler are now reported as user interactions
+
+### 🩹 Fixes
+
+- Controls already on screen when the SDK finishes initializing now report their interactions
+- Masking now warns on the console when a mask cannot be registered, instead of failing silently
+- Interaction reporting can no longer break a host app's own `onPress` handler
+- An interaction that carries no coordinates now omits them, instead of reporting them as `NaN`
+- A `<Text>` with no `onPress` renders untouched, keeping the instrumentation off the most numerous component in a typical app
+- Masking registers each view once instead of on every re-measure, so a long list of masked rows no longer repeats the native call per row per layout pass
+- **Behaviour change:** a `beforeSend` callback that deletes `event.interaction_context`, or replaces it with anything that is not an object, no longer gets the SDK's original put back in its place — only the read-only `is_masked_element` flag is kept, on an otherwise empty object. Previously the coordinates and the reported text were restored, which was the opposite of what the callback asked for. If your callback replaced the container and relied on the SDK restoring it, edit the object in place instead — blank the fields you do not want (`interaction_context.target_element_inner_text = '***'`) or delete just those keys, and everything you leave alone is uploaded as it was
+
+## 0.10.3 (2026-08-30)
+
+### 🩹 Fixes
+
+- Initialization is now safe to run more than once — no duplicate sessions, duplicate events, or crashes
+
+
 ## 0.10.2 (2026-08-25)
 
 ### 🩹 Fixes

package/README.md

@@ -222,6 +222,10 @@ await CoralogixRum.init({
 });
 ```
 
+> [!NOTE]
+> The network instrumentation also injects the W3C `traceparent` header. Setting `network` to `false`
+> stops trace context propagation as well, even when `traceParentInHeader` is enabled.
+
 ### Mobile Vital Detectors
 
 Disable specific mobile vitals detection and collection
@@ -291,6 +295,11 @@ await CoralogixRum.init({
 });
 ```
 
+> [!NOTE]
+> The `traceparent` header is added by the network instrumentation, so this feature depends on it. If
+> you set `instrumentations.network` to `false`, no trace headers are sent even with
+> `enabled: true`.
+
 <!-- /split -->
 <!-- split title="Custom instrumentation" path="features/custom-instrumentation.md" -->
 ### Custom Spans
@@ -618,22 +627,49 @@ Shutdown Session Replay to clean up resources:
 await SessionReplay.shutdown();
 ```
 
-#### Masking Sensitive Content
+<!-- /split -->
+<!-- split title="Masking sensitive content" path="features/masking.md" -->
+### Masking Sensitive Content
 
-To mask sensitive content in your app, use the `onLayout` prop with `SessionReplay.maskView` on any View component that should be masked:
+Masking is not gated on Session Replay. It redacts sensitive content from user-interaction events whether or not you record replays, and when Session Replay is enabled the same mask also hides that content in the recording.
 
-```javascript
+There are two ways to mask, and **`Masked` is recommended**. Mask the whole logical element — the field, the row, the button — rather than an inner fragment of it.
+
+#### `Masked` (recommended)
+
+`Masked` is exported from the plugin itself and needs no Session Replay setup. Wrap anything sensitive in it — it renders a `View` and accepts the `View` props, so it can wrap a whole control or just the sensitive part of one:
+
+```jsx
+import { Text } from 'react-native';
+import { Masked } from '@coralogix/react-native-plugin';
+
+<Masked>
+  <Text>Card: {cardNumber}</Text>
+</Masked>
+```
+
+Do not put `Masked` inside a `<Text>` — wrap the outermost `<Text>` instead.
+
+#### `SessionReplay.maskView`
+
+Alternatively, pass `SessionReplay.maskView` to the `onLayout` prop of any view. It accepts a `LayoutChangeEvent` and works on both the legacy and the New Architecture (Fabric):
+
+```jsx
+import { Text, View } from 'react-native';
 import { SessionReplay } from '@coralogix/react-native-plugin';
 
 <View onLayout={SessionReplay.maskView}>
-  <Text>This text will be masked in session replay</Text>
-  <TextInput placeholder="Password" />
+  <Text>{cardNumber}</Text>
 </View>
 ```
 
-The `SessionReplay.maskView` function accepts a `LayoutChangeEvent` and will mask the view in session replay recordings. It works on both the legacy and the New Architecture (Fabric).
+Attach it to a host component — a custom component that accepts `onLayout` but never forwards it to a real view is silently not masked. Use `Masked` for a `Switch`; `maskView` cannot flag its interactions.
+
+#### Masked interactions
 
+A tap on masked content is still reported, with `interaction_context.target_element_inner_text` redacted to `***` and `interaction_context.is_masked_element: true`. Identity fields and tap coordinates are reported as-is, and a replay recording shows no tap marker. `is_masked_element` is read-only, so use it in `beforeSend` to drop or further redact masked interactions.
 
+Note that `target_element` falls back to `accessibilityLabel`, which is not redacted — give masked keypad keys a shared label (`accessibilityLabel="pin-key"`) rather than the digit they enter.
 <!-- /split -->
 ### Optional - Coralogix Gradle Plugin (Android)
 
@@ -688,4 +724,3 @@ However, the plugin is the only way to capture network activity from third-party
 1. `npm install react-native-url-polyfill`
 2. At the top of your entry-point file (index.js) add:
    `import "react-native-url-polyfill/auto"`
----

package/android/build.gradle

@@ -84,7 +84,10 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 
-  implementation "com.coralogix:android-sdk:2.21.1"
+  // 2.22.0 is the first release exposing View.isCoralogixMasked() and
+  // View.isInsideCoralogixMaskedSubtree(), which the masked-interaction walk in
+  // reportUserInteraction reads instead of reimplementing the SDK's mask rule here.
+  implementation "com.coralogix:android-sdk:2.22.0"
 
   testImplementation "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
   testImplementation "org.mockito:mockito-core:5.12.0"

package/android/src/main/java/com/cxsdk/CxSdkModule.kt

@@ -4,6 +4,8 @@ import android.app.Application
 import android.os.Handler
 import android.os.Looper
 import android.util.Log
+import android.view.View
+import android.view.ViewGroup
 import com.coralogix.android.sdk.CoralogixRum
 import com.coralogix.android.sdk.customspans.CoralogixCustomSpan
 import com.coralogix.android.sdk.customspans.CoralogixGlobalSpan
@@ -29,6 +31,8 @@ import com.coralogix.android.sdk.model.UserContext
 import com.coralogix.android.sdk.model.ViewContext
 import com.coralogix.android.sdk.session_replay.SessionReplay
 import com.coralogix.android.sdk.session_replay.SessionReplay.maskView
+import com.coralogix.android.sdk.session_replay.isCoralogixMasked
+import com.coralogix.android.sdk.session_replay.isInsideCoralogixMaskedSubtree
 import com.coralogix.android.sdk.session_replay.model.SessionReplayOptions
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
@@ -265,8 +269,114 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
       innerText = if (interaction.hasKey("inner_text") && !interaction.isNull("inner_text")) interaction.getString("inner_text") else null,
       x = if (attributesMap?.hasKey("x") == true && attributesMap.isNull("x") == false) attributesMap.getDouble("x") else null,
       y = if (attributesMap?.hasKey("y") == true && attributesMap.isNull("y") == false) attributesMap.getDouble("y") else null,
+      // Present only when JS resolved masking from the component tree. The SDK treats a
+      // non-null value as authoritative and otherwise resolves the coordinates itself,
+      // which is why JS omits the key rather than sending false.
+      isMasked = if (interaction.hasKey("is_masked") && !interaction.isNull("is_masked")) interaction.getBoolean("is_masked") else null,
     )
-    CoralogixRum.reportUserInteraction(details)
+
+    // The tapped control's view tag, sent only when JS could not answer for
+    // itself. It is what lets the walk below see an imperative maskView: that
+    // marks a native view and leaves nothing in the component tree, so JS is
+    // blind to it, while the SDK's own coordinate test cannot tell where the
+    // control begins and ends.
+    val viewTag = if (interaction.hasKey("view_tag") && !interaction.isNull("view_tag"))
+      interaction.getInt("view_tag") else null
+
+    // JS sends one or the other, never both — a verdict it already has needs no
+    // native walk. Checked rather than assumed, because the walk is the expensive
+    // half and an authoritative isMasked would make it wasted work.
+    if (viewTag == null || details.isMasked != null) {
+      CoralogixRum.reportUserInteraction(details)
+      return
+    }
+
+    // Resolving a view and reading its mask tags both require the UI thread, so
+    // reporting becomes asynchronous on this path. This method otherwise runs on
+    // the native-modules thread and reports inline, which means an interaction
+    // carrying a tag can be reported after one that arrived later without a tag.
+    // Interaction spans carry their own timestamps, so ordering is presentational
+    // rather than semantic.
+    UiThreadUtil.runOnUiThread {
+      // Set only when the walk finds a mask; never set to false. A non-null
+      // value is authoritative in the SDK, so a false here would suppress its
+      // coordinate resolution and lose masks the walk cannot see — a masked
+      // overlay that is neither ancestor nor descendant of the control. The SDK
+      // redacts the reported inner text off this flag, so nothing else is needed.
+      //
+      // Descendants count for a click only. A click reports the control's whole
+      // concatenated text, so a masked descendant has to mask the click to keep
+      // the verdict and the text consistent. A scroll reports no text at all, so
+      // the descendant half would buy nothing there and cost plenty: one masked
+      // row anywhere in a list would report every scroll of that list as masked.
+      val masked = isControlMasked(viewTag, includeDescendants = details.type == "click")
+      val resolved = if (masked) details.copy(isMasked = true) else details
+
+      // Straight back off the UI thread. Only the walk above needs it, while
+      // building and handing over the span does not — and every unmasked click
+      // and every scroll carries a tag, so leaving the reporting here would move
+      // the whole interaction path onto the main thread for the majority case
+      // that has nothing to resolve.
+      reactApplicationContext.runOnNativeModulesQueueThread {
+        CoralogixRum.reportUserInteraction(resolved)
+      }
+    }
+  }
+
+  /**
+   * Whether anything in the tapped control is masked: the view itself, an
+   * ancestor, or — when [includeDescendants] is set — anything below it.
+   *
+   * Ancestors always count, because masking is inherited: a control inside a
+   * masked panel is masked. Descendants count for a click, because React Native
+   * renders one logical control as several native views, so
+   * `<TouchableOpacity><Text/></TouchableOpacity>` puts the mask on a child and
+   * leaves the tapped container itself unmarked.
+   *
+   * An unresolvable tag answers false, which omits the flag and leaves the SDK's
+   * coordinate resolution as the backstop — the right outcome for the race this
+   * is most exposed to, a control unmounted between the press and this walk.
+   */
+  private fun isControlMasked(viewTag: Int, includeDescendants: Boolean): Boolean = try {
+    val view = UIManagerHelper.getUIManagerForReactTag(reactApplicationContext, viewTag)
+      ?.resolveView(viewTag)
+    // Self and ancestors through the SDK's own accessor, so the definition of
+    // masked lives in one place.
+    view != null &&
+      (view.isInsideCoralogixMaskedSubtree() ||
+        (includeDescendants && containsMaskedDescendant(view)))
+  } catch (t: Throwable) {
+    Log.d("CxSdkModule", "reportUserInteraction: could not resolve view $viewTag for masking", t)
+    false
+  }
+
+  /**
+   * Breadth-first descendant search for a mask mark, iterative because recursion
+   * on an app-controlled depth is a stack overflow waiting to happen.
+   *
+   * Bounded by [MASK_WALK_NODE_BUDGET]: this runs on the UI thread for every
+   * interaction, so a deep subtree — a long list row, a heavily nested
+   * design-system component — must not be able to cause jank. Exhausting the
+   * budget answers false, leaving the SDK's coordinate resolution as the backstop
+   * rather than claiming an answer the walk never reached.
+   */
+  private fun containsMaskedDescendant(root: View): Boolean {
+    val queue = ArrayDeque<View>()
+    root.enqueueChildren(queue)
+
+    var visited = 0
+    while (queue.isNotEmpty()) {
+      if (visited++ >= MASK_WALK_NODE_BUDGET) return false
+      val current = queue.removeFirst()
+      if (current.isCoralogixMasked()) return true
+      current.enqueueChildren(queue)
+    }
+    return false
+  }
+
+  private fun View.enqueueChildren(queue: ArrayDeque<View>) {
+    val group = this as? ViewGroup ?: return
+    for (i in 0 until group.childCount) queue.addLast(group.getChildAt(i))
   }
 
   @ReactMethod
@@ -327,7 +437,7 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
   }
 
   @ReactMethod
-  override fun maskViewByTag(viewTag: Int) {
+  override fun maskViewByTag(viewTag: Int, promise: Promise) {
     // Resolve the view through the architecture-agnostic UIManagerHelper so this
     // works on both the legacy (Paper) and New (Fabric) architectures.
     // getNativeModule(UIManagerModule) only exists on Paper; under Fabric it
@@ -337,12 +447,23 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
     val context = reactApplicationContext
     // FabricUIManager.resolveView must be called on the UI thread.
     UiThreadUtil.runOnUiThread {
+      // Rejections are the only signal the JS side has: masking that does not
+      // apply is invisible in the app, so an unresolvable tag has to travel back
+      // rather than be swallowed here.
       try {
         val uiManager = UIManagerHelper.getUIManagerForReactTag(context, viewTag)
         val view = uiManager?.resolveView(viewTag)
-        view?.maskView()
+        if (view == null) {
+          promise.reject(
+            MASK_VIEW_ERROR,
+            "view with tag $viewTag could not be resolved, aborting maskViewByTag"
+          )
+          return@runOnUiThread
+        }
+        view.maskView()
+        promise.resolve("view with tag $viewTag marked for masking")
       } catch (t: Throwable) {
-        t.printStackTrace()
+        promise.reject(MASK_VIEW_ERROR, t)
       }
     }
   }
@@ -950,6 +1071,14 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
   companion object {
     const val NAME = "CxSdk"
 
+    // Matches the iOS bridge's rejection code for the same failure.
+    private const val MASK_VIEW_ERROR = "MASK_VIEW_ERROR"
+
+    // Node budget for the descendant half of the masked-control walk. Kept in
+    // step with the iOS bridge's maskWalkNodeBudget so the two platforms give up
+    // at the same tree size.
+    private const val MASK_WALK_NODE_BUDGET = 512
+
     // TODO: replace reflection with a public accessor once the Coralogix Android SDK exposes one —
     // 'getSpan$library_release' is a Kotlin-internal name that may be renamed in a future SDK version.
     internal fun extractOtelIds(child: CoralogixCustomSpan): Pair<String, String>? =

package/android/src/main/java/com/cxsdk/SessionReplayClient.kt

@@ -11,5 +11,5 @@ interface SessionReplayClient {
   fun startSessionRecording()
   fun stopSessionRecording()
   fun captureScreenshot()
-  fun maskViewByTag(viewTag: Int)
+  fun maskViewByTag(viewTag: Int, promise: Promise)
 }