@coralogix/react-native-plugin 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
@@ -282,6 +291,8 @@ await CoralogixRum.init({
 });
 ```
 
+<!-- /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 +342,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 +369,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 +414,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 +469,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 +531,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.
@@ -616,6 +634,7 @@ import { SessionReplay } from '@coralogix/react-native-plugin';
 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).
 
 
+<!-- /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.

package/index.cjs.js

@@ -577,7 +577,7 @@ function stopJsRefreshRateSampler() {
   appStateSub = null;
 }
 
-var version = "0.10.1";
+var version = "0.10.2";
 var pkg = {
 	version: version};
 
@@ -766,9 +766,43 @@ const getUrlFragments = url => {
     return url;
   }
 };
+
+/**
+ * Rolls the session sampling dice.
+ *
+ * This is the only roll for a config without `excludeFromSampling`: `init` pins the
+ * rate it sends to native to 100 in that case, so native does not roll again. See the
+ * comment in `CoralogixRum.init` for why the exclude case is handled the other way round.
+ */
 function isSamplingOn(threshold) {
   return threshold > 0 && Math.random() * 100 <= threshold;
 }
+
+/**
+ * Normalizes `sessionSampleRate` into the shape both native SDKs expect: an
+ * integer percentage in [0, 100].
+ *
+ * The bridges read the value as an integer (`NSNumber.intValue` on iOS,
+ * `ReadableMap.getInt` on Android), so a fractional rate such as `0.5` would be
+ * truncated to `0` on iOS — silently sampling every session out — and can throw
+ * on Android. Round instead, and never round a caller-requested non-zero rate
+ * down to `0`: `0` is the one value that means "emit nothing".
+ */
+function normalizeSessionSampleRate(rate) {
+  if (typeof rate !== 'number' || !Number.isFinite(rate)) {
+    logger.warn(`CoralogixRum: \`sessionSampleRate\` must be a finite number; received ${String(rate)}. Falling back to 100.`);
+    return 100;
+  }
+  if (rate <= 0) {
+    return 0;
+  }
+  if (rate >= 100) {
+    return 100;
+  }
+
+  // Keep a sub-1% request alive rather than truncating it to "emit nothing".
+  return Math.max(1, Math.round(rate));
+}
 function resolveCoralogixOtelWebConfig(config) {
   var _config$sessionSample, _config$view_context;
   const {
@@ -780,7 +814,7 @@ function resolveCoralogixOtelWebConfig(config) {
   OPTIONS_DEFAULTS.ignoreUrls && resolvedIgnoreUrls.push(...OPTIONS_DEFAULTS.ignoreUrls);
   return _extends({}, OPTIONS_DEFAULTS, config, {
     ignoreUrls: resolvedIgnoreUrls,
-    sessionSampleRate: (_config$sessionSample = config.sessionSampleRate) != null ? _config$sessionSample : 100,
+    sessionSampleRate: normalizeSessionSampleRate((_config$sessionSample = config.sessionSampleRate) != null ? _config$sessionSample : 100),
     debug,
     view_context: (_config$view_context = config.view_context) != null ? _config$view_context : OPTIONS_DEFAULTS.view_context
   });
@@ -1033,6 +1067,9 @@ function createErrorProxy(errorMessage) {
   });
 }
 let isInited = false;
+// Whether native, rather than JS, rolled the sampling for this init. Only in that mode can
+// `CoralogixRum.isInited` be true while native has no RUM behind it.
+let nativeOwnsSamplingRoll = false;
 let fetchInstrumentation;
 function toSafeRecord(name, value) {
   if (value == null) {
@@ -1049,7 +1086,7 @@ const CoralogixRum = {
     return isInited;
   },
   init: async function (options) {
-    var _resolvedOptions$debu, _resolvedOptions$excl, _resolvedOptions$excl2;
+    var _options$debug, _resolvedOptions$excl, _resolvedOptions$excl2;
     if (isInited) {
       console.warn('[Coralogix React Native SDK] - already initialized');
       return;
@@ -1058,13 +1095,28 @@ const CoralogixRum = {
       console.warn('[Coralogix React Native SDK] - `public_key` is required and must be a non-empty string; initialization aborted.');
       return;
     }
+
+    // Configure the logger first: resolving the options normalizes `sessionSampleRate`,
+    // which warns about an invalid rate. Doing it the other way round swallowed that
+    // warning on the first init — exactly when the caller needs to see it.
+    logger.shouldLog = (_options$debug = options.debug) != null ? _options$debug : false;
     const resolvedOptions = resolveCoralogixOtelWebConfig(options);
-    logger.shouldLog = (_resolvedOptions$debu = resolvedOptions.debug) != null ? _resolvedOptions$debu : false;
+
+    // The rate has to be applied exactly *once*. Rolling it on both sides squared it:
+    // `sessionSampleRate: 1` kept ~0.01% of sessions instead of 1%.
+    //
+    // Without `excludeFromSampling`, JS rolls and the rate sent to native is pinned to 100
+    // so native does not roll again; a losing roll returns here, which also keeps JS
+    // instrumentation off a session that would emit nothing. With `excludeFromSampling`,
+    // only native can honour "sampled out, but still emit these categories", so JS does not
+    // roll and forwards the real rate — pinning to 100 there would sample every session in.
     const hasExcludeOverrides = ((_resolvedOptions$excl = (_resolvedOptions$excl2 = resolvedOptions.excludeFromSampling) == null ? void 0 : _resolvedOptions$excl2.length) != null ? _resolvedOptions$excl : 0) > 0;
-    if (!isSamplingOn(resolvedOptions.sessionSampleRate) && !hasExcludeOverrides) {
+    if (!hasExcludeOverrides && !isSamplingOn(resolvedOptions.sessionSampleRate)) {
       logger.debug('CoralogixRum: Session tracking is disabled');
       return;
     }
+    nativeOwnsSamplingRoll = hasExcludeOverrides;
+    const nativeSessionSampleRate = hasExcludeOverrides ? resolvedOptions.sessionSampleRate : 100;
     await registerCoralogixInstrumentations(resolvedOptions);
     let finalOptions;
     const lastNavRoute = getLastNavigationRouteDetected();
@@ -1095,6 +1147,7 @@ const CoralogixRum = {
       });
     }
     await CxSdk.initialize(_extends({}, finalOptions, {
+      sessionSampleRate: nativeSessionSampleRate,
       frameworkVersion: pkg.version,
       networkExtraConfig: finalOptions.networkExtraConfig ? serializeNetworkCaptureRules(finalOptions.networkExtraConfig) : undefined,
       hasBeforeSend: !!finalOptions.beforeSend,
@@ -1280,7 +1333,21 @@ const SessionReplay = {
       logger.warn("invalid options in SessionReplay.init: ", options);
       return false;
     }
-    return await CxSdk.initializeSessionReplay(options);
+    try {
+      // iOS resolves the string "initializeSessionReplay success" rather than a boolean,
+      // so coerce instead of handing a truthy string back through a `Promise<boolean>`.
+      return !!(await CxSdk.initializeSessionReplay(options));
+    } catch (e) {
+      // When native owns the sampling roll, a sampled-out session leaves no native RUM
+      // behind and iOS rejects rather than resolving. That is an expected outcome, not a
+      // failure, so report it as `false` like the guards above rather than surfacing an
+      // unhandled rejection. Every other rejection is a real error and stays the caller's.
+      if (!nativeOwnsSamplingRoll) {
+        throw e;
+      }
+      logger.warn('SessionReplay.init: no native RUM for this session (sampled out); replay not started.', e);
+      return false;
+    }
   },
   shutdown: async () => {
     logger.debug("session replay: shutdown called");

package/index.esm.js

@@ -575,7 +575,7 @@ function stopJsRefreshRateSampler() {
   appStateSub = null;
 }
 
-var version = "0.10.1";
+var version = "0.10.2";
 var pkg = {
 	version: version};
 
@@ -764,9 +764,43 @@ const getUrlFragments = url => {
     return url;
   }
 };
+
+/**
+ * Rolls the session sampling dice.
+ *
+ * This is the only roll for a config without `excludeFromSampling`: `init` pins the
+ * rate it sends to native to 100 in that case, so native does not roll again. See the
+ * comment in `CoralogixRum.init` for why the exclude case is handled the other way round.
+ */
 function isSamplingOn(threshold) {
   return threshold > 0 && Math.random() * 100 <= threshold;
 }
+
+/**
+ * Normalizes `sessionSampleRate` into the shape both native SDKs expect: an
+ * integer percentage in [0, 100].
+ *
+ * The bridges read the value as an integer (`NSNumber.intValue` on iOS,
+ * `ReadableMap.getInt` on Android), so a fractional rate such as `0.5` would be
+ * truncated to `0` on iOS — silently sampling every session out — and can throw
+ * on Android. Round instead, and never round a caller-requested non-zero rate
+ * down to `0`: `0` is the one value that means "emit nothing".
+ */
+function normalizeSessionSampleRate(rate) {
+  if (typeof rate !== 'number' || !Number.isFinite(rate)) {
+    logger.warn(`CoralogixRum: \`sessionSampleRate\` must be a finite number; received ${String(rate)}. Falling back to 100.`);
+    return 100;
+  }
+  if (rate <= 0) {
+    return 0;
+  }
+  if (rate >= 100) {
+    return 100;
+  }
+
+  // Keep a sub-1% request alive rather than truncating it to "emit nothing".
+  return Math.max(1, Math.round(rate));
+}
 function resolveCoralogixOtelWebConfig(config) {
   var _config$sessionSample, _config$view_context;
   const {
@@ -778,7 +812,7 @@ function resolveCoralogixOtelWebConfig(config) {
   OPTIONS_DEFAULTS.ignoreUrls && resolvedIgnoreUrls.push(...OPTIONS_DEFAULTS.ignoreUrls);
   return _extends({}, OPTIONS_DEFAULTS, config, {
     ignoreUrls: resolvedIgnoreUrls,
-    sessionSampleRate: (_config$sessionSample = config.sessionSampleRate) != null ? _config$sessionSample : 100,
+    sessionSampleRate: normalizeSessionSampleRate((_config$sessionSample = config.sessionSampleRate) != null ? _config$sessionSample : 100),
     debug,
     view_context: (_config$view_context = config.view_context) != null ? _config$view_context : OPTIONS_DEFAULTS.view_context
   });
@@ -1031,6 +1065,9 @@ function createErrorProxy(errorMessage) {
   });
 }
 let isInited = false;
+// Whether native, rather than JS, rolled the sampling for this init. Only in that mode can
+// `CoralogixRum.isInited` be true while native has no RUM behind it.
+let nativeOwnsSamplingRoll = false;
 let fetchInstrumentation;
 function toSafeRecord(name, value) {
   if (value == null) {
@@ -1047,7 +1084,7 @@ const CoralogixRum = {
     return isInited;
   },
   init: async function (options) {
-    var _resolvedOptions$debu, _resolvedOptions$excl, _resolvedOptions$excl2;
+    var _options$debug, _resolvedOptions$excl, _resolvedOptions$excl2;
     if (isInited) {
       console.warn('[Coralogix React Native SDK] - already initialized');
       return;
@@ -1056,13 +1093,28 @@ const CoralogixRum = {
       console.warn('[Coralogix React Native SDK] - `public_key` is required and must be a non-empty string; initialization aborted.');
       return;
     }
+
+    // Configure the logger first: resolving the options normalizes `sessionSampleRate`,
+    // which warns about an invalid rate. Doing it the other way round swallowed that
+    // warning on the first init — exactly when the caller needs to see it.
+    logger.shouldLog = (_options$debug = options.debug) != null ? _options$debug : false;
     const resolvedOptions = resolveCoralogixOtelWebConfig(options);
-    logger.shouldLog = (_resolvedOptions$debu = resolvedOptions.debug) != null ? _resolvedOptions$debu : false;
+
+    // The rate has to be applied exactly *once*. Rolling it on both sides squared it:
+    // `sessionSampleRate: 1` kept ~0.01% of sessions instead of 1%.
+    //
+    // Without `excludeFromSampling`, JS rolls and the rate sent to native is pinned to 100
+    // so native does not roll again; a losing roll returns here, which also keeps JS
+    // instrumentation off a session that would emit nothing. With `excludeFromSampling`,
+    // only native can honour "sampled out, but still emit these categories", so JS does not
+    // roll and forwards the real rate — pinning to 100 there would sample every session in.
     const hasExcludeOverrides = ((_resolvedOptions$excl = (_resolvedOptions$excl2 = resolvedOptions.excludeFromSampling) == null ? void 0 : _resolvedOptions$excl2.length) != null ? _resolvedOptions$excl : 0) > 0;
-    if (!isSamplingOn(resolvedOptions.sessionSampleRate) && !hasExcludeOverrides) {
+    if (!hasExcludeOverrides && !isSamplingOn(resolvedOptions.sessionSampleRate)) {
       logger.debug('CoralogixRum: Session tracking is disabled');
       return;
     }
+    nativeOwnsSamplingRoll = hasExcludeOverrides;
+    const nativeSessionSampleRate = hasExcludeOverrides ? resolvedOptions.sessionSampleRate : 100;
     await registerCoralogixInstrumentations(resolvedOptions);
     let finalOptions;
     const lastNavRoute = getLastNavigationRouteDetected();
@@ -1093,6 +1145,7 @@ const CoralogixRum = {
       });
     }
     await CxSdk.initialize(_extends({}, finalOptions, {
+      sessionSampleRate: nativeSessionSampleRate,
       frameworkVersion: pkg.version,
       networkExtraConfig: finalOptions.networkExtraConfig ? serializeNetworkCaptureRules(finalOptions.networkExtraConfig) : undefined,
       hasBeforeSend: !!finalOptions.beforeSend,
@@ -1278,7 +1331,21 @@ const SessionReplay = {
       logger.warn("invalid options in SessionReplay.init: ", options);
       return false;
     }
-    return await CxSdk.initializeSessionReplay(options);
+    try {
+      // iOS resolves the string "initializeSessionReplay success" rather than a boolean,
+      // so coerce instead of handing a truthy string back through a `Promise<boolean>`.
+      return !!(await CxSdk.initializeSessionReplay(options));
+    } catch (e) {
+      // When native owns the sampling roll, a sampled-out session leaves no native RUM
+      // behind and iOS rejects rather than resolving. That is an expected outcome, not a
+      // failure, so report it as `false` like the guards above rather than surfacing an
+      // unhandled rejection. Every other rejection is a real error and stays the caller's.
+      if (!nativeOwnsSamplingRoll) {
+        throw e;
+      }
+      logger.warn('SessionReplay.init: no native RUM for this session (sampled out); replay not started.', e);
+      return false;
+    }
   },
   shutdown: async () => {
     logger.debug("session replay: shutdown called");

package/package.json

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

package/src/model/Types.d.ts

@@ -260,7 +260,17 @@ export interface CoralogixBrowserSdkConfig {
     fpsSamplingSeconds?: number;
     /** Sets a value for the `environment` attribute */
     environment?: string;
-    /** Percentage of overall sessions being tracked, defaults to 100%  */
+    /**
+     * Percentage of overall sessions being tracked, defaults to 100%.
+     *
+     * The rate is applied exactly once. Without `excludeFromSampling` the plugin
+     * rolls it and the native SDK is told 100; with `excludeFromSampling` set the
+     * native SDK rolls it, since only native can emit the excluded categories for a
+     * sampled-out session.
+     *
+     * Expressed as a whole percentage in [0, 100]; a fractional value is rounded
+     * (never down to 0) because the native bridges read it as an integer.
+     */
     sessionSampleRate?: number;
     /**
      * Event categories that bypass session sampling. Events of these categories are

package/src/utils.d.ts

@@ -1,5 +1,23 @@
 import { CoralogixBrowserSdkConfig } from './model/Types';
 export declare const hrTimeToMilliseconds: ([seconds, nanoseconds]: [number, number]) => number;
 export declare const getUrlFragments: (url: string) => string;
+/**
+ * Rolls the session sampling dice.
+ *
+ * This is the only roll for a config without `excludeFromSampling`: `init` pins the
+ * rate it sends to native to 100 in that case, so native does not roll again. See the
+ * comment in `CoralogixRum.init` for why the exclude case is handled the other way round.
+ */
 export declare function isSamplingOn(threshold: number): boolean;
+/**
+ * Normalizes `sessionSampleRate` into the shape both native SDKs expect: an
+ * integer percentage in [0, 100].
+ *
+ * The bridges read the value as an integer (`NSNumber.intValue` on iOS,
+ * `ReadableMap.getInt` on Android), so a fractional rate such as `0.5` would be
+ * truncated to `0` on iOS — silently sampling every session out — and can throw
+ * on Android. Round instead, and never round a caller-requested non-zero rate
+ * down to `0`: `0` is the one value that means "emit nothing".
+ */
+export declare function normalizeSessionSampleRate(rate: unknown): number;
 export declare function resolveCoralogixOtelWebConfig(config: CoralogixBrowserSdkConfig): CoralogixBrowserSdkConfig;