Open in ChatGPTOpen in Claude

Official Coralogix React Native plugin

This package replaces the old @coralogix/react-native-sdk package.

Links

• Changelog
• Coralogix Real User Monitoring

Usage

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. init is an async function.

import { CoralogixRum } from '@coralogix/react-native-plugin'

await CoralogixRum.init({
  application: 'app-name',
  environment: 'production',
  public_key: 'abc-123-456',
  coralogixDomain: 'EU2',
  version: 'v1.0.3',
  labels: {
    payment: 'visa',
  },
  ignoreErrors: ['some error message to ignore'],
  ignoreUrls: [/.*\.svg/, /.*\.ico/], // will ignore all requests to .svg and .ico files 
  sessionSampleRate: 100, // Percentage of overall sessions being tracked, Default to 100%
});

The native SDK applies sessionSampleRate once per session, including each new session after the previous one expires. Set it to a whole percentage in 0-100. The plugin rounds a fractional value to an integer, and never rounds a non-zero rate down to 0, because the native bridges read the value as an integer.

A sampled-out session still initializes the SDK and, when traceParentInHeader is enabled, still adds the traceparent header to outgoing requests, so backend traces stay correlated. Beyond that it reports nothing unless excludeFromSampling lists at least one category: no initialization event, and no session_replay_init even when Session Replay starts. List a category and that category is reported, together with the SDK's own internal events.

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().

import { CoralogixRum } from '@coralogix/react-native-plugin';

// Update user context dynamically
CoralogixRum.setUserContext({
  user_id: '123',
  user_name: 'name',
  user_email: 'user@email.com',
  account_id: 'acc-42', // optional, from 0.12.0
  account_name: 'Acme Corp', // optional, from 0.12.0
  user_metadata: {
    role: 'admin',
    // ...
  },
});

// Update custom labels dynamically
CoralogixRum.setLabels({
  ...CoralogixRum.getLabels(),
  paymentMethod: 'visa',
  userTheme: 'dark',
  // ...
});

// Update application context dynamically
CoralogixRum.setApplicationContext({
  application: 'app-name',
  version: '1.0.0',
});

CoralogixRum.log(CoralogixLogSeverity.Error, 'this is a log', { key: 'value' });
CoralogixRum.error('this is a log with error severity', { key: 'value' });

Optional - Coralogix Gradle plugin (Android)

The Coralogix Gradle Plugin automatically instruments all OkHttp clients in your app (including third-party SDKs) at build time. This ensures that all network traffic is automatically traced and reported to Coralogix, with no manual setup or code changes required. This plugin is especially useful for instrumenting networking libraries that create their own OkHttpClient instances internally and would otherwise be impossible to monitor.

Apply the plugin

1. Add the plugin to your project classpath
   In your project-level build.gradle file:

   buildscript {
       dependencies {
           classpath "com.coralogix.gradle.plugin:gradle-plugin:0.0.2"
       }
   }

2. Apply the plugin in your app module
   At the top of your app-level build.gradle file:

   apply plugin: "com.coralogix.gradle.plugin"

Configure the plugin

The plugin exposes a simple Gradle extension you can use in your app module:

coralogix {
  // Enable or disable instrumentation (default: true)
  enabled = true

  // Print debug logs during the build process (default: false)
  log = false
}

If the default configuration suits your needs, you can safely omit this block — the defaults will apply automatically.

Note

This plugin is optional. Regular JavaScript fetch calls and standard network requests will still be instrumented without it.

However, the plugin is the only way to capture network activity from third-party libraries or SDKs that use their own OkHttpClient instances internally.

iOS SDK through Swift package manager

By default, pod install installs the native Coralogix iOS SDK (the Coralogix, CoralogixInternal and SessionReplay pods) from CocoaPods trunk. CocoaPods trunk stops accepting new pods on 2 December 2026, so native iOS SDK releases after that date are available only through Swift Package Manager.

From plugin version 0.17.0, on React Native 0.75 or later, set CX_IOS_SDK_SPM=1 and build your pods as dynamic frameworks when you run pod install:

cd ios
CX_IOS_SDK_SPM=1 USE_FRAMEWORKS=dynamic pod install

To keep both set for everyone who builds the app, add them at the top of your ios/Podfile instead:

ENV['CX_IOS_SDK_SPM'] = '1'
ENV['USE_FRAMEWORKS'] = 'dynamic'

The plugin then adds the cx-ios-sdk Swift package to its pod, at the native SDK version that plugin version pins, and React Native links it into your app. You don't need to change your Xcode project.

Warning

Keep the pods as dynamic frameworks. With React Native's default static libraries, or with static frameworks (USE_FRAMEWORKS=static), Xcode 16 links the SDK into the app twice and the build fails with duplicate symbol errors. Other libraries in your app may need their own fixes to build as dynamic frameworks. If your app can't use dynamic frameworks, keep installing the SDK from CocoaPods.

Note

On React Native earlier than 0.75, CX_IOS_SDK_SPM=1 has no effect: pod install prints a warning and installs the SDK from CocoaPods trunk.

Troubleshooting

URL.origin is not implemented

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"