@coralogix/react-native-plugin 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 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
+
+- `sessionSampleRate` is now applied once instead of twice — the configured percentage was being rolled on both the JavaScript and native sides, so a rate of 1% collected roughly 0.01% of sessions
+- A fractional `sessionSampleRate` such as `0.5` is now rounded to a whole percentage instead of being truncated to `0` on iOS, which silently sampled out every session
+- `SessionReplay.init()` now resolves `false` instead of rejecting when the session was sampled out, and resolves a real boolean on both platforms
+
 ## 0.10.1 (2026-08-11)
 
 ### 🩹 Fixes

package/README.md

@@ -12,7 +12,7 @@ This package replaces the old `@coralogix/react-native-sdk` package.
 
 To use Coralogix SDK, call `CoralogixRum.init(options)` at the soonest available moment after the app loads.
 This will initialize the SDK based on the options you provided.
-Please note that `init` is an `async` function.
+`init` is an `async` function.
 
 ```javascript
 import { CoralogixRum } from '@coralogix/react-native-plugin'
@@ -32,6 +32,11 @@ await CoralogixRum.init({
 });
 ```
 
+`sessionSampleRate` is a whole percentage in `0`-`100` and is applied **once**. A
+fractional value is rounded to an integer before it is forwarded (and a non-zero
+rate is never rounded down to `0`), because the native bridges read the value as
+an integer.
+
 To provide contextual information or transmit manual logs, utilize the exported functions of `CoralogixRum`.
 Keep in mind that these functions will remain inactive until you've invoked `CoralogixRum.init()`.
 
@@ -67,6 +72,7 @@ CoralogixRum.log(CoralogixLogSeverity.Error, 'this is a log', { key: 'value' });
 CoralogixRum.error('this is a log with error severity', { key: 'value' });
 ```
 
+<!-- split title="Logs, errors, and views" path="features/logs-errors-and-views.md" -->
 ### Custom Logs
 
 Send structured logs with optional data and labels.
@@ -80,9 +86,10 @@ CoralogixRum.debug('this is a debug log', {key: 'value', pi: 3.14});
 CoralogixRum.error('this is an error log', {error: 'yes', is_bad: 'no'});
 ```
 
-> **Note:** Due to ReactNative limitations, not all value types are supported for the log data values,
-> our testing shows that ReactNative can't pass some types to the coralogix native layer, types we have identified as problematic are `Map`, `Set`, `Date` and `Function`
-> please note that there could be more, so for example:
+> [!NOTE]
+> Due to React Native limitations, not all value types are supported for the log data values.
+> Our testing shows that React Native can't pass some types to the coralogix native layer; the ones we have identified as problematic are `Map`, `Set`, `Date` and `Function`.
+> There could be more. For example:
 > ```javascript
 > // this would pass as an empty object to the coralogix native layer, same for Set and Date:
 > CoralogixRum.debug('this will be a problem', {key: new Map().set(1, 2)});
@@ -90,7 +97,7 @@ CoralogixRum.error('this is an error log', {error: 'yes', is_bad: 'no'});
 > // this would pass as null to the coralogix native layer
 > CoralogixRum.debug('this will be a problem too', {key: () => {}});
 > ```
-> in the event that you need to use any of these types please stringify them before you pass it to the `log` method
+> If you need to pass any of these types, stringify them before you pass them to the `log` method.
 
 ### Error Reporting
 
@@ -193,6 +200,8 @@ subsequent events belong to a fresh session with a new session id.
 CoralogixRum.createNewSession();
 ```
 
+<!-- /split -->
+<!-- split title="Configuration options" path="configuration/options.md" -->
 ### Instrumentation's
 
 Turn on/off specific instrumentation; defaults to true for all.
@@ -213,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
@@ -282,6 +295,13 @@ 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
 
 Create manual RUM spans to instrument custom flows in your application. Requires `traceParentInHeader.enabled: true`.
@@ -331,7 +351,8 @@ Pass instrument names to prevent network requests, errors, or interactions fired
 const tracer = CoralogixRum.getCustomTracer(['networkRequests', 'userInteractions', 'errors']);
 ```
 
-> **Note:** Only one global span may be active at a time. `startGlobalSpan` returns `null` if a global span is already open.
+> [!NOTE]
+> Only one global span may be active at a time. `startGlobalSpan` returns `null` if a global span is already open.
 
 ### Time Measurement
 
@@ -357,6 +378,8 @@ CoralogixRum.endTimeMeasure('checkout');
 - Unmatched `endTimeMeasure` calls are dropped silently by the native SDK.
 - Calling `startTimeMeasure` again with an open `name` overwrites the previous start.
 
+<!-- /split -->
+<!-- split title="Exporting and networking" path="configuration/exporting-and-networking.md" -->
 ### Traces Exporter
 
 Receive OTLP-formatted trace batches from the native SDK in your JavaScript code. Use this to forward spans to an OTLP-compatible backend (e.g. Jaeger, custom collector) alongside Coralogix.
@@ -400,7 +423,8 @@ The callback receives a `TraceExporterData` object following the OTLP JSON forma
 }
 ```
 
-> **Note:** The callback fires once per native export batch, which typically contains several spans rather than one per span.
+> [!NOTE]
+> The callback fires once per native export batch, which typically contains several spans rather than one per span.
 
 ### beforeSend
 
@@ -454,7 +478,8 @@ await CoralogixRum.init({
 });
 ```
 
-> **Note:** always read it as `isSessionSampledIn ?? true`. The field is absent on
+> [!NOTE]
+> Always read it as `isSessionSampledIn ?? true`. The field is absent on
 > native SDKs that predate it, and the SDK never invents a value it was not given.
 
 `isSessionSampledIn` is read-only: it reports the SDK's sampling decision for the
@@ -515,6 +540,8 @@ await CoralogixRum.init({
 });
 ```
 
+<!-- /split -->
+<!-- split title="Session Replay" path="features/session-replay.md" -->
 ### Session Replay
 
 Session Replay allows you to record and replay user sessions to understand user behavior and debug issues.
@@ -600,22 +627,50 @@ 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)
 
 The Coralogix Gradle Plugin automatically instruments all OkHttp clients in your app (including third-party SDKs) at build time.
@@ -669,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)
 }