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. Please note that 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%
});

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: '[email protected]',
  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' });

Custom Logs

Send structured logs with optional data and labels.

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

Shorthand signatures exists for all log severities:

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:

// 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)});

// 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

View Tracking

To track views, set the view context whenever a view changes.

CoralogixRum.setViewContext({
  view: 'Home',
});

You can automatically track view changes by using react-navigation. Wrap your navigation ref with our attachReactNavigationObserver hook like so:

const navigationRef = createNavigationContainerRef();
const navHooks = attachReactNavigationObserver(navigationRef);

<NavigationContainer
  ref={navigationRef}
  onReady={navHooks.onReady}
  onStateChange={navHooks.onStateChange}
>
  >{/* ... */}
</NavigationContainer>

Instrumentation's

Turn on/off specific instrumentation; defaults to true for all. Each instrumentation is responsible for which data the SDK will track and collect for you.

await CoralogixRum.init({
  // ...
  instrumentations: {
    errors: true,
    custom: true,
    mobile_vitals: true,
    anr: true,
    lifecycle: true,
    user_interaction: true,
    network: true
  },
});

Mobile Vital Detectors

Disable specific mobile vitals detection and collection

await CoralogixRum.init({
  // ...
  mobileVitals: {
    warm: true,
    cold: true,
    cpu: true,
    memory: true,
    rendering: true,
    slowFrozenFrames: true,
  }
});

Ignore Errors

The ignoreErrors option allows you to exclude errors that meet specific criteria. This options accepts a set of strings and regular expressions to match against the event's error message. Use regular expressions for exact matching as strings remove partial matches.

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

await CoralogixRum.init({
  // ...
  ignoreErrors: [/Exact Match Error Message/, 'partial/match'],
});

TraceParentInHeader

Add trace context propagation in headers across service boundaries

await CoralogixRum.init({
  // ...
  traceParentInHeader: {
    enabled: true
  },
});

beforeSend

Enable event access and modification before sending to Coralogix, supporting content modification, and event discarding.

await CoralogixRum.init({
  // ...
  beforeSend: (event) => {
    // Discard events from @company.com users.
    if (event.session_context.user_email?.endsWith('@company.com')) {
      return null;
    }

    // Redact sensitive information.
    event.session_context.user_email = '***@***';

    return event;
  },
});

Proxy URL

Proxy configuration to route requests.
By specifying a proxy URL, all RUM data will be directed to this URL via the POST method. However, it is necessary for this data to be subsequently relayed from the proxy to Coralogix. The Coralogix route for each request that is sent to the proxy is available in the request's cxforward parameter (for example, https://www.your-proxy.com/endpoint?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs).

await CoralogixRum.init({
  // ...
  coralogixDomain: 'EU1',
  proxyUrl: 'https://www.your-proxy.com/endpoint',
});

Session Replay

Session Replay allows you to record and replay user sessions to understand user behavior and debug issues.

Initialize Session Replay

To initialize Session Replay, call SessionReplay.init(options) with the desired configuration options.

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

await SessionReplay.init({
  captureScale: 0.5,                    // Scale factor for screenshots (0.0 to 1.0)
  captureCompressQuality: 0.8,         // Compression quality for screenshots (0.0 to 1.0)
  sessionRecordingSampleRate: 100,      // Percentage of sessions to record (0 to 100)
  autoStartSessionRecording: true,      // Automatically start recording when initialized
  maskAllTexts: true,                   // Mask all text content by default (optional, default: true)
  textsToMask: ['password', '^card.*'], // Array of strings/regex patterns for specific text masking (optional)
  maskAllImages: false,                 // Mask all images (optional, default: false)
});

Options:

• captureScale (required): Scale factor for screenshots. Must be between 0.0 and 1.0. Lower values reduce file size but may decrease quality.
• captureCompressQuality (required): Compression quality for screenshots. Must be between 0.0 and 1.0. Higher values improve quality but increase file size.
• sessionRecordingSampleRate (required): Percentage of sessions to record. Must be between 0 and 100. Use 100 to record all sessions.
• autoStartSessionRecording (required): If true, recording starts automatically after initialization. If false, you must manually call startSessionRecording().
• maskAllTexts (optional): If true, all text content is masked by default. Defaults to true.
• textsToMask (optional): Array of strings or regex patterns to mask specific text content. Only used when maskAllTexts is false.
• maskAllImages (optional): If true, all images are masked. Defaults to false.

Check Initialization Status

Check if Session Replay has been initialized:

const isInited = await SessionReplay.isInited();
console.log('Session Replay initialized:', isInited);

Check Recording Status

Check if Session Replay is currently recording:

const isRecording = await SessionReplay.isRecording();
console.log('Session Replay recording:', isRecording);

Start Recording

Manually start session recording:

SessionReplay.startSessionRecording();

Note: If autoStartSessionRecording is set to true in the init options, recording starts automatically and you don't need to call this method.

Stop Recording

Manually stop session recording:

SessionReplay.stopSessionRecording();

Capture Screenshot

Manually capture a screenshot during a session:

SessionReplay.captureScreenshot();

This is useful for capturing specific moments in the user journey that you want to highlight.

Shutdown Session Replay

Shutdown Session Replay to clean up resources:

await SessionReplay.shutdown();

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:

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

<View onLayout={SessionReplay.maskView}>
  <Text>This text will be masked in session replay</Text>
  <TextInput placeholder="Password" />
</View>

The SessionReplay.maskView function accepts a LayoutChangeEvent and will mask the view in session replay recordings.

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.

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"