---
title: React Native
description: This guide covers installing and configuring the Coralogix RUM SDK in a React Native application, including the options it accepts, the events it instruments, and how to report errors and views.
url: https://coralogix.com/docs/user-guides/rum/sdk-installation/react-native/react-native-plugin/
product: ingress
feature: RUM Ingress
feature_id: rum.ingress
feature_identifier: ingress/rum.ingress
last_updated: '2026-08-12'
---
# Official Coralogix React Native plugin
[](https://www.npmjs.com/package/@coralogix/react-native-plugin)
This package replaces the old `@coralogix/react-native-sdk` package.
## Links
* [Changelog](https://coralogix.github.io/cx-react-native-plugin/CHANGELOG.html)
* [Coralogix Real User Monitoring](https://coralogix.com/docs/user-guides/rum/getting-started/real-user-monitoring.md)
## 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"`