@coralogix/react-native-plugin 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.9.0 (2026-07-29)
+
+### 🚀 Features
+
+- add data & labels to React Native reportError
+
+### ⬆️ Dependency Updates
+
+- Native iOS SDK bumped to **2.13.2**
+- Native Android SDK bumped to **2.19.2**
+
+## 0.8.0 (2026-07-29)
+
+### 🚀 Features
+
+- expose isSessionSampledIn to beforeSend + make SDK-owned event fields read-only
+
+### ⬆️ Dependency Updates
+
+- Native iOS SDK bumped to **2.13.1**
+- Native Android SDK bumped to **2.19.1**
+
+## 0.7.2 (2026-07-20)
+
+### 🩹 Fixes
+
+- drain every beforeSend delivery during the fatal flush
+- flush crash events before fatal-error handover
+
 ## 0.7.1 (2026-07-09)
 
 ### 🩹 Fixes

package/CxSdk.podspec

@@ -16,9 +16,9 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
-  s.dependency 'Coralogix','2.10.0'
-  s.dependency 'CoralogixInternal','2.10.0'
-  s.dependency 'SessionReplay','2.10.0'
+  s.dependency 'Coralogix','2.13.2'
+  s.dependency 'CoralogixInternal','2.13.2'
+  s.dependency 'SessionReplay','2.13.2'
 
   # 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.

package/README.md

@@ -92,6 +92,72 @@ CoralogixRum.error('this is an error log', {error: 'yes', is_bad: 'no'});
 > ```
 > in the event that you need to use any of these types please stringify them before you pass it to the `log` method
 
+### Error Reporting
+
+Report handled errors with optional structured data and labels. **Choose one of the variants below per error event** — each call generates a single error report.
+
+**Parameters:**
+- `error` (Error): The error object to report.
+- `isCrash` (boolean): Whether this error represents a crash (`true`) or a handled exception (`false`).
+- `data` (optional): Structured data object attached to the error event. Empty objects are omitted.
+- `labels` (optional): Key-value pairs for categorizing the error event. Empty objects are omitted.
+
+**Variant 1: Basic error reporting**
+
+```javascript
+import { CoralogixRum } from '@coralogix/react-native-plugin';
+
+try {
+  await processPayment(order);
+} catch (error) {
+  CoralogixRum.reportError(error, false);
+}
+```
+
+**Variant 2: With structured data**
+
+```javascript
+try {
+  await processPayment(order);
+} catch (error) {
+  CoralogixRum.reportError(error, false, {
+    orderId: '12345',
+    paymentMethod: 'visa',
+    amount: 99.99,
+  });
+}
+```
+
+**Variant 3: With data and labels**
+
+```javascript
+try {
+  await processPayment(order);
+} catch (error) {
+  CoralogixRum.reportError(
+    error,
+    false,
+    { orderId: '12345', amount: 99.99 },
+    { team: 'payments', severity: 'high' }
+  );
+}
+```
+
+**Reporting crashes:**
+
+```javascript
+try {
+  await criticalOperation();
+} catch (error) {
+  CoralogixRum.reportError(
+    error,
+    true, // isCrash = true
+    { operation: 'criticalTask', stage: 'initialization' },
+    { environment: 'production' }
+  );
+}
+```
+
 ### View Tracking
 
 To track views, set the view context whenever a view changes.
@@ -184,6 +250,10 @@ await CoralogixRum.init({
 Allowed values: `'errors'`, `'logs'`, `'network'`, `'userInteractions'`,
 `'mobileVitals'`, `'customSpan'`, `'customMeasurement'`.
 
+Inside a [`beforeSend`](#beforesend) callback, `session_context.isSessionSampledIn`
+tells you whether an event came from a sampled-in session or reached you only via
+`excludeFromSampling`, so excluded categories can be filtered further.
+
 ### Ignore Errors
 
 The ignoreErrors option allows you to exclude errors that meet specific criteria.
@@ -353,6 +423,82 @@ await CoralogixRum.init({
 });
 ```
 
+#### Telling excluded events apart in `beforeSend`
+
+Every event carries `session_context.isSessionSampledIn`. `false` means the event
+reached you only because its category is listed in
+[`excludeFromSampling`](#exclude-from-sampling) — the session itself was sampled
+out. Use it to apply your own filtering on top of the exclude list, for example to
+keep only error-severity events from sampled-out sessions:
+
+```javascript
+await CoralogixRum.init({
+  // ...
+  sessionSampleRate: 10,
+  excludeFromSampling: ['errors', 'logs'],
+  beforeSend: (event) => {
+    // Default to `true`: a native SDK older than the one this plugin pins does not
+    // stamp the flag, and `!undefined` would drop everything but errors.
+    const sampledIn = event.session_context.isSessionSampledIn ?? true;
+
+    // Session sampled out: forward only error-severity events, drop the rest.
+    if (
+      !sampledIn &&
+      event.event_context?.severity !== CoralogixLogSeverity.Error
+    ) {
+      return null;
+    }
+
+    return event;
+  },
+});
+```
+
+> **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
+session, so assigning to it has no effect on the sent event. The decision is
+recorded when the event is created, so events buffered across a session rotation
+keep the decision of the session they belong to.
+
+#### Read-only fields
+
+Some fields exist for the callback to *read*, not to change. The SDK restores its
+own values after `beforeSend` returns, so assigning to any of them — or injecting
+one into a returned object — has no effect on the sent event.
+
+Inside `session_context`, **only** the user fields are editable:
+
+| Editable | Read-only |
+| --- | --- |
+| `user_id`, `user_name`, `user_email`, `user_metadata` | `session_id`, `session_creation_date`, `isSessionSampledIn`, `hasRecording` |
+
+Any other key in `session_context` — including one your callback invents — is
+discarded, so session identity cannot be forged.
+
+Deleting an editable field is honored, since redaction-by-deletion is a valid use.
+That means returning a *hand-built partial* `session_context` drops the user fields
+you left out; edit the event you were given (or spread it) if you want to change
+one field and keep the rest.
+
+These top-level fields are read-only too, because rewriting them would corrupt
+trace correlation, event dedup or product analytics rather than redact anything:
+
+`spanId`, `traceId`, `fingerPrint`, `timestamp`, `platform`, `mobile_sdk`,
+`snapshot_context`, `isSnapshotEvent`, `prev_session`, `view_number`,
+`isNavigationEvent`
+
+`view_number` and `isNavigationEvent` record what the SDK observed when it built
+the event. They are deliberately not recomputed from `event_context.type`, so if
+you relabel an event the two can differ — filter on `isNavigationEvent` when you
+need "was this actually a navigation".
+
+Everything else — `event_context` (including `severity`), `labels`,
+`error_context`, `log_context`, `network_request_context`, `view_context`,
+`environment`, `device_context`, `device_state`, `version_metadata` — is editable,
+and returning `null` still drops the event entirely.
+
 ### Proxy URL
 
 Proxy configuration to route requests.  

package/android/build.gradle

@@ -84,7 +84,7 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 
-  implementation "com.coralogix:android-sdk:2.17.1"
+  implementation "com.coralogix:android-sdk:2.19.2"
 
   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

@@ -182,17 +182,33 @@ class CxSdkModule(reactContext: ReactApplicationContext) :
       ?.mapValues { it.value as Any }
       ?.takeIf { it.isNotEmpty() }
 
+    val eventLabels: Map<String, Any>? = details.getMap("labels")
+      ?.toStringAnyMap()
+      ?.filterValues { it != null }
+      ?.mapValues { it.value as Any }
+      ?.takeIf { it.isNotEmpty() }
+
     CoralogixRum.reportError(
       CoralogixErrorDecorator(
         errorType = errorType,
         errorMessage = message,
         errorStack = CoralogixStackTrace(parsedStackFrames),
         isCrash = isCrash,
-        customAttributes = customAttributes
+        customAttributes = customAttributes,
+        labels = eventLabels
       )
     )
   }
 
+  @ReactMethod
+  override fun flushSpans(promise: Promise) {
+    // Force-flushes the batch processor and resolves once the export/upload
+    // attempt finishes — the same contract as iOS. Called by the JS fatal-error
+    // handler before it hands over to the framework's default handler, which
+    // terminates the process.
+    CoralogixRum.flush { promise.resolve("flushSpans success") }
+  }
+
   @ReactMethod
   override fun sendCxSpanData(results: ReadableArray) {
     val data = convertStrictReadableArrayToListOfMaps(results)

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

@@ -19,6 +19,7 @@ interface RUMClient {
   fun startTimeMeasure(name: String, labels: ReadableMap?)
   fun endTimeMeasure(name: String)
   fun reportError(details: ReadableMap)
+  fun flushSpans(promise: Promise)
   fun sendCxSpanData(results: ReadableArray)
   fun reportMobileVitalsMeasurement(type: String, value: Double, units: String)
   fun reportMobileVitalsMeasurementSet(type: String, metrics: ReadableArray)

package/index.cjs.js

@@ -17,6 +17,18 @@ function _extends() {
   }, _extends.apply(null, arguments);
 }
 
+let CoralogixEventType = /*#__PURE__*/function (CoralogixEventType) {
+  CoralogixEventType["ERROR"] = "error";
+  CoralogixEventType["NETWORK_REQUEST"] = "network-request";
+  CoralogixEventType["LOG"] = "log";
+  CoralogixEventType["USER_INTERACTION"] = "user-interaction";
+  CoralogixEventType["WEB_VITALS"] = "web-vitals";
+  CoralogixEventType["LONG_TASK"] = "longtask";
+  CoralogixEventType["RESOURCES"] = "resources";
+  CoralogixEventType["INTERNAL"] = "internal";
+  CoralogixEventType["NAVIGATION"] = "navigation";
+  return CoralogixEventType;
+}({});
 let CoralogixLogSeverity = /*#__PURE__*/function (CoralogixLogSeverity) {
   CoralogixLogSeverity[CoralogixLogSeverity["Debug"] = 1] = "Debug";
   CoralogixLogSeverity[CoralogixLogSeverity["Verbose"] = 2] = "Verbose";
@@ -27,6 +39,27 @@ let CoralogixLogSeverity = /*#__PURE__*/function (CoralogixLogSeverity) {
   return CoralogixLogSeverity;
 }({});
 
+/** Versions of the plugin and the underlying native SDK that produced an event. */
+
+/**
+ * A RUM event as it goes on the wire.
+ *
+ * Fields marked `readonly` are SDK-owned: span identity, dedup keys, SDK-owned
+ * counters and the SDK's own observations. `beforeSend` may read them, but the
+ * SDK's value is always restored after the callback returns — assigning to one
+ * has no effect on the sent event.
+ */
+
+/**
+ * The view of an event that `beforeSend` receives.
+ *
+ * Only the user fields of `session_context` are editable — session identity, the
+ * sampling decision and the recording flag are SDK-owned and are restored from
+ * the SDK's own values after the callback returns. The same holds for the
+ * `readonly` fields inherited from {@link CxRumEvent}. Nothing a callback writes
+ * to those can reach the wire, so they cannot be forged.
+ */
+
 /**
  * Instrumentation names that can be excluded from a custom tracer's span context.
  * Pass one or more values to `getCustomTracer()` to prevent those event types from
@@ -130,10 +163,17 @@ class CoralogixErrorInstrumentation extends instrumentation.InstrumentationBase
     const defaultHandler = ErrorUtils.getGlobalHandler();
     ErrorUtils.setGlobalHandler((error, isFatal) => {
       this.report(error, isFatal);
-      if (defaultHandler) {
-        setTimeout(() => {
-          defaultHandler(error, isFatal);
-        }, 2500);
+      if (!defaultHandler) {
+        return;
+      }
+      if (isFatal) {
+        // In release builds the default handler terminates the app (RCTFatal),
+        // killing any crash event still queued in the native batch processor —
+        // flush it out first. waitForFatalErrorFlush never rejects and is
+        // time-capped, so the handover is guaranteed.
+        waitForFatalErrorFlush().catch(() => undefined).finally(() => defaultHandler(error, isFatal));
+      } else {
+        defaultHandler(error, isFatal);
       }
     });
     this.listenToConsoleError();
@@ -537,7 +577,7 @@ function stopJsRefreshRateSampler() {
   appStateSub = null;
 }
 
-var version = "0.7.1";
+var version = "0.9.0";
 var pkg = {
 	version: version};
 
@@ -1210,7 +1250,7 @@ const CoralogixRum = {
     }
     CxSdk.endTimeMeasure(name);
   },
-  reportError: (error, isCrash, data) => {
+  reportError: (error, isCrash, data, labels) => {
     if (!isInited) {
       logger.debug('CoralogixRum must be initiated before error reporting');
       return;
@@ -1224,6 +1264,9 @@ const CoralogixRum = {
     if (data && Object.keys(data).length > 0) {
       errorDetails.data = data;
     }
+    if (labels && Object.keys(labels).length > 0) {
+      errorDetails.labels = labels;
+    }
     CxSdk.reportError(errorDetails);
   }
 };
@@ -1389,10 +1432,115 @@ const parseErrorStack = error => {
     return null;
   }).filter(frame => frame !== null);
 };
+const FATAL_FLUSH_MAX_WAIT_MS = 2500;
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Best-effort delivery of a crash before a fatal error is handed back to RN's
+ * default handler, which terminates the app in release builds. `flushSpans`
+ * force-flushes the native batch processor; the native SDK uploads crash events
+ * directly (bypassing the beforeSend round trip) and resolves once the upload
+ * attempt finishes, so awaiting it is the full crash-delivery guarantee.
+ * Never rejects; resolves within FATAL_FLUSH_MAX_WAIT_MS.
+ *
+ * @internal Used by the error instrumentation — not part of the public API.
+ */
+const waitForFatalErrorFlush = async () => {
+  const flush = Promise.resolve(CxSdk.flushSpans()).catch(e => logger.debug('flushSpans failed:', e));
+  await Promise.race([flush, delay(FATAL_FLUSH_MAX_WAIT_MS)]);
+};
 
 // Create event emitter
 const eventEmitter = new reactNative.NativeEventEmitter(CxSdk);
 
+/**
+ * The only `session_context` fields a `beforeSend` callback may change. Every
+ * other field there is SDK-owned — session identity, the sampling decision, the
+ * recording flag — and is restored from the SDK's own values after the callback
+ * runs.
+ *
+ * Deliberately an allowlist rather than a list of protected fields: a session
+ * field added by a future native SDK is then read-only by default instead of
+ * silently becoming forgeable. Matches the Android SDK, whose `EditableCxRum`
+ * only accepts a user context, so nothing else in the session can be rewritten.
+ */
+const EDITABLE_SESSION_FIELDS = ['user_id', 'user_name', 'user_email', 'user_metadata'];
+
+/**
+ * Top-level `cx_rum` keys a callback must not change: span identity, dedup keys,
+ * SDK-owned counters and the SDK's own observations. A rewrite here would corrupt
+ * trace correlation or downstream funnel analysis rather than redact anything.
+ *
+ * Mirrors the native SDKs' read-only set. `view_number` and `isNavigationEvent`
+ * are included for the same reason they are natively: they record what the SDK
+ * saw at build time, not a property derived from the (possibly relabelled) event.
+ */
+const READ_ONLY_CX_RUM_KEYS = ['snapshot_context', 'isSnapshotEvent', 'mobile_sdk', 'timestamp', 'traceId', 'spanId', 'fingerPrint', 'prev_session', 'platform', 'view_number', 'isNavigationEvent'];
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Deep copy of a value that came off the native bridge, so a callback mutating a
+ * nested object in place cannot also mutate the snapshot we restore from. Bridge
+ * payloads are JSON by construction; anything exotic is returned as-is rather
+ * than throwing, since a failed snapshot must not drop the event.
+ */
+const cloneBridgeValue = value => {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (e) {
+    return value;
+  }
+};
+
+/**
+ * Rebuilds `session_context` from the SDK's own values, copying over only the
+ * fields in {@link EDITABLE_SESSION_FIELDS}. Anything the callback rewrote or
+ * invented outside that set is discarded.
+ *
+ * @param merged   `session_context` as it stands after the callback ran.
+ * @param original `session_context` snapshotted *before* the callback ran.
+ */
+const rebuildSessionContext = (merged, original) => {
+  // The SDK always sends a session_context. If it somehow did not, a callback
+  // must not be able to invent one — session identity would be forgeable through
+  // exactly the gap this function exists to close.
+  if (!isPlainObject(original)) {
+    return original;
+  }
+  // A callback that replaced session_context with a non-object (or dropped it)
+  // gets the SDK's version back wholesale: there are no edits to salvage, and
+  // native would otherwise fail to decode and drop the whole event.
+  if (!isPlainObject(merged)) {
+    return original;
+  }
+  const rebuilt = _extends({}, original);
+  for (const key of EDITABLE_SESSION_FIELDS) {
+    if (key in merged) {
+      rebuilt[key] = merged[key];
+    } else {
+      // Removing a user field is a legitimate redaction, so honor the deletion.
+      delete rebuilt[key];
+    }
+  }
+  return rebuilt;
+};
+
+/** Puts the SDK's values back on the read-only top-level keys, in place. */
+const restoreReadOnlyCxRumKeys = (merged, protectedValues) => {
+  for (const key of READ_ONLY_CX_RUM_KEYS) {
+    if (key in protectedValues) {
+      merged[key] = protectedValues[key];
+    } else {
+      // Native never sent this key, so a callback must not be able to fabricate
+      // one that looks like it came from the SDK.
+      delete merged[key];
+    }
+  }
+};
+
 // Subscribe to beforeSend events
 const subscription = eventEmitter.addListener('onBeforeSend', events => {
   // logger.log("📨 onBeforeSend triggered with events: ", events)
@@ -1411,14 +1559,45 @@ const subscription = eventEmitter.addListener('onBeforeSend', events => {
       const results = [];
       for (const fullEvent of events) {
         const event = fullEvent.text.cx_rum;
+
+        // Snapshot everything SDK-owned *before* the callback runs. Callbacks
+        // routinely mutate the event in place (the documented redaction example
+        // does) and `event` is the very object nested in `fullEvent`, so reading
+        // these afterwards would just hand back the callback's own edits. The
+        // snapshot is deep so an in-place edit to a nested object (say
+        // `event.mobile_sdk.sdk_version`) can't tamper with it either.
+        const protectedValues = {};
+        if (isPlainObject(event)) {
+          for (const key of READ_ONLY_CX_RUM_KEYS) {
+            if (key in event) {
+              protectedValues[key] = cloneBridgeValue(event[key]);
+            }
+          }
+        }
+        const protectedSessionContext = cloneBridgeValue(event == null ? void 0 : event.session_context);
         const res = beforeSendCallback(event);
         if (!res) {
           continue;
         }
+        // A truthy non-object return means the callback malfunctioned. Discard its
+        // edits rather than trusting it: spreading a string would splatter index
+        // keys across cx_rum, and forwarding the event untouched would skip the
+        // restores below — letting an in-place tamper through on the one path that
+        // never gets checked.
+        let edits = {};
+        if (isPlainObject(res)) {
+          edits = res;
+        } else {
+          logger.debug('⚠️ beforeSend returned a non-object; discarding its edits');
+        }
+
         // Merge the result from each event
+        const mergedCxRum = _extends({}, fullEvent.text.cx_rum, edits);
+        mergedCxRum.session_context = rebuildSessionContext(mergedCxRum.session_context, protectedSessionContext);
+        restoreReadOnlyCxRumKeys(mergedCxRum, protectedValues);
         const mergeEvent = _extends({}, fullEvent, {
           text: _extends({}, fullEvent.text, {
-            cx_rum: _extends({}, fullEvent.text.cx_rum, res)
+            cx_rum: mergedCxRum
           })
         });
         results.push(mergeEvent);
@@ -1438,6 +1617,7 @@ const subscription = eventEmitter.addListener('onBeforeSend', events => {
 exports.CoralogixCustomSpan = CoralogixCustomSpan;
 exports.CoralogixCustomTracer = CoralogixCustomTracer;
 exports.CoralogixDomain = CoralogixDomain;
+exports.CoralogixEventType = CoralogixEventType;
 exports.CoralogixGlobalSpan = CoralogixGlobalSpan;
 exports.CoralogixLogSeverity = CoralogixLogSeverity;
 exports.CoralogixRum = CoralogixRum;
@@ -1445,3 +1625,4 @@ exports.CxSdk = CxSdk;
 exports.SessionReplay = SessionReplay;
 exports.attachReactNavigationObserver = attachReactNavigationObserver;
 exports.parseErrorStack = parseErrorStack;
+exports.waitForFatalErrorFlush = waitForFatalErrorFlush;

package/index.esm.js

@@ -15,6 +15,18 @@ function _extends() {
   }, _extends.apply(null, arguments);
 }
 
+let CoralogixEventType = /*#__PURE__*/function (CoralogixEventType) {
+  CoralogixEventType["ERROR"] = "error";
+  CoralogixEventType["NETWORK_REQUEST"] = "network-request";
+  CoralogixEventType["LOG"] = "log";
+  CoralogixEventType["USER_INTERACTION"] = "user-interaction";
+  CoralogixEventType["WEB_VITALS"] = "web-vitals";
+  CoralogixEventType["LONG_TASK"] = "longtask";
+  CoralogixEventType["RESOURCES"] = "resources";
+  CoralogixEventType["INTERNAL"] = "internal";
+  CoralogixEventType["NAVIGATION"] = "navigation";
+  return CoralogixEventType;
+}({});
 let CoralogixLogSeverity = /*#__PURE__*/function (CoralogixLogSeverity) {
   CoralogixLogSeverity[CoralogixLogSeverity["Debug"] = 1] = "Debug";
   CoralogixLogSeverity[CoralogixLogSeverity["Verbose"] = 2] = "Verbose";
@@ -25,6 +37,27 @@ let CoralogixLogSeverity = /*#__PURE__*/function (CoralogixLogSeverity) {
   return CoralogixLogSeverity;
 }({});
 
+/** Versions of the plugin and the underlying native SDK that produced an event. */
+
+/**
+ * A RUM event as it goes on the wire.
+ *
+ * Fields marked `readonly` are SDK-owned: span identity, dedup keys, SDK-owned
+ * counters and the SDK's own observations. `beforeSend` may read them, but the
+ * SDK's value is always restored after the callback returns — assigning to one
+ * has no effect on the sent event.
+ */
+
+/**
+ * The view of an event that `beforeSend` receives.
+ *
+ * Only the user fields of `session_context` are editable — session identity, the
+ * sampling decision and the recording flag are SDK-owned and are restored from
+ * the SDK's own values after the callback returns. The same holds for the
+ * `readonly` fields inherited from {@link CxRumEvent}. Nothing a callback writes
+ * to those can reach the wire, so they cannot be forged.
+ */
+
 /**
  * Instrumentation names that can be excluded from a custom tracer's span context.
  * Pass one or more values to `getCustomTracer()` to prevent those event types from
@@ -128,10 +161,17 @@ class CoralogixErrorInstrumentation extends InstrumentationBase {
     const defaultHandler = ErrorUtils.getGlobalHandler();
     ErrorUtils.setGlobalHandler((error, isFatal) => {
       this.report(error, isFatal);
-      if (defaultHandler) {
-        setTimeout(() => {
-          defaultHandler(error, isFatal);
-        }, 2500);
+      if (!defaultHandler) {
+        return;
+      }
+      if (isFatal) {
+        // In release builds the default handler terminates the app (RCTFatal),
+        // killing any crash event still queued in the native batch processor —
+        // flush it out first. waitForFatalErrorFlush never rejects and is
+        // time-capped, so the handover is guaranteed.
+        waitForFatalErrorFlush().catch(() => undefined).finally(() => defaultHandler(error, isFatal));
+      } else {
+        defaultHandler(error, isFatal);
       }
     });
     this.listenToConsoleError();
@@ -535,7 +575,7 @@ function stopJsRefreshRateSampler() {
   appStateSub = null;
 }
 
-var version = "0.7.1";
+var version = "0.9.0";
 var pkg = {
 	version: version};
 
@@ -1208,7 +1248,7 @@ const CoralogixRum = {
     }
     CxSdk.endTimeMeasure(name);
   },
-  reportError: (error, isCrash, data) => {
+  reportError: (error, isCrash, data, labels) => {
     if (!isInited) {
       logger.debug('CoralogixRum must be initiated before error reporting');
       return;
@@ -1222,6 +1262,9 @@ const CoralogixRum = {
     if (data && Object.keys(data).length > 0) {
       errorDetails.data = data;
     }
+    if (labels && Object.keys(labels).length > 0) {
+      errorDetails.labels = labels;
+    }
     CxSdk.reportError(errorDetails);
   }
 };
@@ -1387,10 +1430,115 @@ const parseErrorStack = error => {
     return null;
   }).filter(frame => frame !== null);
 };
+const FATAL_FLUSH_MAX_WAIT_MS = 2500;
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Best-effort delivery of a crash before a fatal error is handed back to RN's
+ * default handler, which terminates the app in release builds. `flushSpans`
+ * force-flushes the native batch processor; the native SDK uploads crash events
+ * directly (bypassing the beforeSend round trip) and resolves once the upload
+ * attempt finishes, so awaiting it is the full crash-delivery guarantee.
+ * Never rejects; resolves within FATAL_FLUSH_MAX_WAIT_MS.
+ *
+ * @internal Used by the error instrumentation — not part of the public API.
+ */
+const waitForFatalErrorFlush = async () => {
+  const flush = Promise.resolve(CxSdk.flushSpans()).catch(e => logger.debug('flushSpans failed:', e));
+  await Promise.race([flush, delay(FATAL_FLUSH_MAX_WAIT_MS)]);
+};
 
 // Create event emitter
 const eventEmitter = new NativeEventEmitter(CxSdk);
 
+/**
+ * The only `session_context` fields a `beforeSend` callback may change. Every
+ * other field there is SDK-owned — session identity, the sampling decision, the
+ * recording flag — and is restored from the SDK's own values after the callback
+ * runs.
+ *
+ * Deliberately an allowlist rather than a list of protected fields: a session
+ * field added by a future native SDK is then read-only by default instead of
+ * silently becoming forgeable. Matches the Android SDK, whose `EditableCxRum`
+ * only accepts a user context, so nothing else in the session can be rewritten.
+ */
+const EDITABLE_SESSION_FIELDS = ['user_id', 'user_name', 'user_email', 'user_metadata'];
+
+/**
+ * Top-level `cx_rum` keys a callback must not change: span identity, dedup keys,
+ * SDK-owned counters and the SDK's own observations. A rewrite here would corrupt
+ * trace correlation or downstream funnel analysis rather than redact anything.
+ *
+ * Mirrors the native SDKs' read-only set. `view_number` and `isNavigationEvent`
+ * are included for the same reason they are natively: they record what the SDK
+ * saw at build time, not a property derived from the (possibly relabelled) event.
+ */
+const READ_ONLY_CX_RUM_KEYS = ['snapshot_context', 'isSnapshotEvent', 'mobile_sdk', 'timestamp', 'traceId', 'spanId', 'fingerPrint', 'prev_session', 'platform', 'view_number', 'isNavigationEvent'];
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Deep copy of a value that came off the native bridge, so a callback mutating a
+ * nested object in place cannot also mutate the snapshot we restore from. Bridge
+ * payloads are JSON by construction; anything exotic is returned as-is rather
+ * than throwing, since a failed snapshot must not drop the event.
+ */
+const cloneBridgeValue = value => {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (e) {
+    return value;
+  }
+};
+
+/**
+ * Rebuilds `session_context` from the SDK's own values, copying over only the
+ * fields in {@link EDITABLE_SESSION_FIELDS}. Anything the callback rewrote or
+ * invented outside that set is discarded.
+ *
+ * @param merged   `session_context` as it stands after the callback ran.
+ * @param original `session_context` snapshotted *before* the callback ran.
+ */
+const rebuildSessionContext = (merged, original) => {
+  // The SDK always sends a session_context. If it somehow did not, a callback
+  // must not be able to invent one — session identity would be forgeable through
+  // exactly the gap this function exists to close.
+  if (!isPlainObject(original)) {
+    return original;
+  }
+  // A callback that replaced session_context with a non-object (or dropped it)
+  // gets the SDK's version back wholesale: there are no edits to salvage, and
+  // native would otherwise fail to decode and drop the whole event.
+  if (!isPlainObject(merged)) {
+    return original;
+  }
+  const rebuilt = _extends({}, original);
+  for (const key of EDITABLE_SESSION_FIELDS) {
+    if (key in merged) {
+      rebuilt[key] = merged[key];
+    } else {
+      // Removing a user field is a legitimate redaction, so honor the deletion.
+      delete rebuilt[key];
+    }
+  }
+  return rebuilt;
+};
+
+/** Puts the SDK's values back on the read-only top-level keys, in place. */
+const restoreReadOnlyCxRumKeys = (merged, protectedValues) => {
+  for (const key of READ_ONLY_CX_RUM_KEYS) {
+    if (key in protectedValues) {
+      merged[key] = protectedValues[key];
+    } else {
+      // Native never sent this key, so a callback must not be able to fabricate
+      // one that looks like it came from the SDK.
+      delete merged[key];
+    }
+  }
+};
+
 // Subscribe to beforeSend events
 const subscription = eventEmitter.addListener('onBeforeSend', events => {
   // logger.log("📨 onBeforeSend triggered with events: ", events)
@@ -1409,14 +1557,45 @@ const subscription = eventEmitter.addListener('onBeforeSend', events => {
       const results = [];
       for (const fullEvent of events) {
         const event = fullEvent.text.cx_rum;
+
+        // Snapshot everything SDK-owned *before* the callback runs. Callbacks
+        // routinely mutate the event in place (the documented redaction example
+        // does) and `event` is the very object nested in `fullEvent`, so reading
+        // these afterwards would just hand back the callback's own edits. The
+        // snapshot is deep so an in-place edit to a nested object (say
+        // `event.mobile_sdk.sdk_version`) can't tamper with it either.
+        const protectedValues = {};
+        if (isPlainObject(event)) {
+          for (const key of READ_ONLY_CX_RUM_KEYS) {
+            if (key in event) {
+              protectedValues[key] = cloneBridgeValue(event[key]);
+            }
+          }
+        }
+        const protectedSessionContext = cloneBridgeValue(event == null ? void 0 : event.session_context);
         const res = beforeSendCallback(event);
         if (!res) {
           continue;
         }
+        // A truthy non-object return means the callback malfunctioned. Discard its
+        // edits rather than trusting it: spreading a string would splatter index
+        // keys across cx_rum, and forwarding the event untouched would skip the
+        // restores below — letting an in-place tamper through on the one path that
+        // never gets checked.
+        let edits = {};
+        if (isPlainObject(res)) {
+          edits = res;
+        } else {
+          logger.debug('⚠️ beforeSend returned a non-object; discarding its edits');
+        }
+
         // Merge the result from each event
+        const mergedCxRum = _extends({}, fullEvent.text.cx_rum, edits);
+        mergedCxRum.session_context = rebuildSessionContext(mergedCxRum.session_context, protectedSessionContext);
+        restoreReadOnlyCxRumKeys(mergedCxRum, protectedValues);
         const mergeEvent = _extends({}, fullEvent, {
           text: _extends({}, fullEvent.text, {
-            cx_rum: _extends({}, fullEvent.text.cx_rum, res)
+            cx_rum: mergedCxRum
           })
         });
         results.push(mergeEvent);
@@ -1433,4 +1612,4 @@ const subscription = eventEmitter.addListener('onBeforeSend', events => {
   }
 });
 
-export { CoralogixCustomSpan, CoralogixCustomTracer, CoralogixDomain, CoralogixGlobalSpan, CoralogixLogSeverity, CoralogixRum, CxSdk, SessionReplay, attachReactNavigationObserver, parseErrorStack };
+export { CoralogixCustomSpan, CoralogixCustomTracer, CoralogixDomain, CoralogixEventType, CoralogixGlobalSpan, CoralogixLogSeverity, CoralogixRum, CxSdk, SessionReplay, attachReactNavigationObserver, parseErrorStack, waitForFatalErrorFlush };

package/ios/CxSdk.mm

@@ -64,6 +64,9 @@ RCT_EXTERN_METHOD(reportNetworkRequest:(NSDictionary *)networkRequestDictionary
                   withResolver:(RCTPromiseResolveBlock)resolve
                   withRejecter:(RCTPromiseRejectBlock)reject)
 
+RCT_EXTERN_METHOD(flushSpans:(RCTPromiseResolveBlock)resolve
+                  withRejecter:(RCTPromiseRejectBlock)reject)
+
 RCT_EXTERN_METHOD(sendCxSpanData:(NSArray *)beforeSendResults
                   withResolver:(RCTPromiseResolveBlock)resolve
                   withRejecter:(RCTPromiseRejectBlock)reject)

package/ios/CxSdk.swift

@@ -237,18 +237,38 @@ class CxSdk: RCTEventEmitter {
     let message = dictionary[Keys.errorMessage.rawValue] as? String ?? ""
     let errorType = dictionary[Keys.errorType.rawValue] as? String ?? "5"
     let isCrash = dictionary[Keys.isCrash.rawValue] as? Bool ?? false
-    // Pass `data` only when non-empty — an empty dict would surface
-    // `error_context.data = {}` on the emitted RUM event.
+    // Pass `data`/`labels` only when non-empty — an empty dict would surface an
+    // empty `error_context.error_custom_data` (or labels) on the emitted RUM event.
     let customAttributes = (dictionary["data"] as? [String: Any]).flatMap { $0.isEmpty ? nil : $0 }
+    let labels = (dictionary["labels"] as? [String: Any]).flatMap { $0.isEmpty ? nil : $0 }
 
     coralogixRum?.reportError(message: message,
                               stackTrace: stackTrace,
                               errorType: errorType,
                               isCrash: isCrash,
-                              customAttributes: customAttributes)
+                              customAttributes: customAttributes,
+                              labels: labels)
     resolve("reportError success")
   }
 
+  @objc(flushSpans:withRejecter:)
+  func flushSpans(resolve: @escaping RCTPromiseResolveBlock,
+                  reject: @escaping RCTPromiseRejectBlock) -> Void {
+    // Force-flushes the batch processor and resolves once the export/upload
+    // attempt finishes — the same public SDK API the Android bridge calls.
+    // Invoked by the JS fatal-error handler before it hands over to RN's default
+    // handler, which terminates the process in release builds. `flush` handles
+    // its own threading and always invokes completion (immediately when the SDK
+    // is not initialized), so callers never hang.
+    guard let coralogixRum else {
+      resolve("flushSpans success")
+      return
+    }
+    coralogixRum.flush {
+      resolve("flushSpans success")
+    }
+  }
+
   @objc(sendCxSpanData:withResolver:withRejecter:)
   func sendCxSpanData(beforeSendResults: NSArray,
                       resolve:RCTPromiseResolveBlock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralogix/react-native-plugin",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Official Coralogix React Native plugin",
   "license": "Apache-2.0",
   "author": "Coralogix",

package/src/index.d.ts

@@ -25,6 +25,14 @@ interface CxSdkClient {
     endTimeMeasure(name: string): void;
     reportError(details: Record<string, unknown>): void;
     reportNetworkRequest(details: NetworkRequestDetails): void;
+    /**
+     * Forces immediate export of natively queued telemetry. iOS drains the batch
+     * processor and resolves after the upload attempt; Android resolves
+     * immediately WITHOUT flushing (the native SDK exposes no flush API yet), so
+     * a resolved promise must not be read as delivery there — see
+     * waitForFatalErrorFlush for the Android fallback.
+     */
+    flushSpans(): Promise<string>;
     shutdown(): Promise<boolean>;
     createNewSession(): Promise<boolean>;
     sendCxSpanData(results: CxSpan[]): void;
@@ -56,11 +64,22 @@ export declare const CxSdk: CxSdkClient;
 export declare const CoralogixRum: CoralogixOtelWebType;
 export declare const SessionReplay: SessionReplayType;
 export declare const parseErrorStack: (error: Error) => CoralogixStackFrame[];
+/**
+ * Best-effort delivery of a crash before a fatal error is handed back to RN's
+ * default handler, which terminates the app in release builds. `flushSpans`
+ * force-flushes the native batch processor; the native SDK uploads crash events
+ * directly (bypassing the beforeSend round trip) and resolves once the upload
+ * attempt finishes, so awaiting it is the full crash-delivery guarantee.
+ * Never rejects; resolves within FATAL_FLUSH_MAX_WAIT_MS.
+ *
+ * @internal Used by the error instrumentation — not part of the public API.
+ */
+export declare const waitForFatalErrorFlush: () => Promise<void>;
 export { type ApplicationContextConfig } from './model/ApplicationContextConfig';
 export { type ViewContextConfig } from './model/ViewContextConfig';
 export { CoralogixDomain } from './model/CoralogixDomain';
 export { type UserContextConfig } from './model/UserContextConfig';
-export { type CoralogixBrowserSdkConfig, type CoralogixIgnoredInstrument, type ExcludableInstrumentation, type NetworkCaptureRule, type TraceExporterData, CoralogixLogSeverity, } from './model/Types';
+export { type CoralogixBrowserSdkConfig, type CoralogixIgnoredInstrument, type ExcludableInstrumentation, type NetworkCaptureRule, type TraceExporterData, type EditableCxRumEvent, type BeforeSendResult, CoralogixEventType, CoralogixLogSeverity, } from './model/Types';
 export { type CoralogixOtelWebOptionsInstrumentations } from './model/CoralogixOtelWebOptionsInstrumentations';
 export { type CustomMeasurement } from './model/CustomMeasurement';
 export { type NetworkRequestDetails } from './model/NetworkRequestDetails';

package/src/model/CoralogixOtelWebType.d.ts

@@ -59,7 +59,7 @@ export interface CoralogixOtelWebType extends SendLog {
      * Unknown names are dropped silently by the native SDK.
      */
     endTimeMeasure: (name: string) => void;
-    reportError: (error: Error, isCrash: boolean, data?: Record<string, unknown>) => void;
+    reportError: (error: Error, isCrash: boolean, data?: Record<string, unknown>, labels?: Record<string, unknown>) => void;
     /**
      * Report a network request to the underlying Coralogix SDK
      * @param details

package/src/model/Types.d.ts

@@ -28,6 +28,28 @@ export interface SessionContext extends UserMetadata {
     device: string | undefined;
     os: string | undefined;
     osVersion: string | number | undefined;
+    /**
+     * Whether the session this event belongs to was sampled in. `false` means the
+     * event reached export only because its category is listed in
+     * `excludeFromSampling` while the session itself was sampled out.
+     *
+     * Read-only: it records the SDK's sampling decision for the session, so
+     * assigning to it inside `beforeSend` has no effect on the sent event. The
+     * decision is stamped on each event when it is created, so events buffered
+     * across a session rotation keep the decision of the session they belong to.
+     *
+     * Optional because a native SDK older than the version this plugin pins does
+     * not stamp it, and the SDK never fabricates a value it did not receive. Treat
+     * `undefined` as `true` — the native SDKs use the same default, since an
+     * unstamped event can only have reached export on a sampled-in session.
+     */
+    readonly isSessionSampledIn?: boolean;
+    /** Whether Session Replay was recording for this session. Read-only. */
+    readonly hasRecording?: boolean;
+    /** Session identity. Read-only — the SDK owns it. */
+    readonly session_id?: string;
+    /** Session start time. Read-only — the SDK owns it. */
+    readonly session_creation_date?: number;
 }
 export interface DeviceState {
     battery: string | undefined;
@@ -114,8 +136,25 @@ export interface SnapshotContext {
     actionCount: number;
     hasRecording: boolean;
 }
+/** Versions of the plugin and the underlying native SDK that produced an event. */
+export interface MobileSdkMetadata {
+    readonly framework?: string;
+    readonly os?: string;
+    /** Version of `@coralogix/react-native-plugin`. */
+    readonly sdk_version?: string;
+    /** Version of the native iOS/Android Coralogix SDK. */
+    readonly native_version?: string;
+}
+/**
+ * A RUM event as it goes on the wire.
+ *
+ * Fields marked `readonly` are SDK-owned: span identity, dedup keys, SDK-owned
+ * counters and the SDK's own observations. `beforeSend` may read them, but the
+ * SDK's value is always restored after the callback returns — assigning to one
+ * has no effect on the sent event.
+ */
 export interface CxRumEvent {
-    platform: string;
+    readonly platform: string;
     version_metadata: VersionMetaData;
     session_context: SessionContext;
     device_context: DeviceContext;
@@ -125,16 +164,39 @@ export interface CxRumEvent {
     error_context?: ErrorContext;
     log_context?: LogContext;
     network_request_context?: NetworkRequestContext;
-    snapshot_context?: SnapshotContext;
+    readonly snapshot_context?: SnapshotContext;
     labels: CoralogixRumLabels;
-    spanId: string;
-    traceId: string;
+    readonly spanId: string;
+    readonly traceId: string;
     environment: string;
-    timestamp: number;
-    isSnapshotEvent?: boolean;
+    readonly timestamp: number;
+    readonly isSnapshotEvent?: boolean;
+    /** SDK/framework versions. Read-only. */
+    readonly mobile_sdk?: MobileSdkMetadata;
+    /** Event dedup key. Read-only. */
+    readonly fingerPrint?: string;
+    /** Previous session identity, present only after a session rotation. Read-only. */
+    readonly prev_session?: Record<string, unknown>;
+    /** SDK-owned per-session navigation step counter. Read-only. */
+    readonly view_number?: number | null;
+    /**
+     * Whether the SDK observed a navigation when it built this event. Read-only,
+     * and intentionally not recomputed from `event_context.type` — it records what
+     * the SDK saw, so it can legitimately diverge from a relabelled event type.
+     */
+    readonly isNavigationEvent?: boolean;
 }
+/**
+ * The view of an event that `beforeSend` receives.
+ *
+ * Only the user fields of `session_context` are editable — session identity, the
+ * sampling decision and the recording flag are SDK-owned and are restored from
+ * the SDK's own values after the callback returns. The same holds for the
+ * `readonly` fields inherited from {@link CxRumEvent}. Nothing a callback writes
+ * to those can reach the wire, so they cannot be forged.
+ */
 export interface EditableCxRumEvent extends Omit<CxRumEvent, 'session_context' | 'timestamp' | 'snapshot_context'> {
-    session_context: Pick<SessionContext, keyof UserMetadata>;
+    session_context: Pick<SessionContext, keyof UserMetadata | 'isSessionSampledIn'>;
 }
 export type BeforeSendResult = EditableCxRumEvent | null;
 export interface NetworkCaptureRule {