@kloudmate/rum-react-native

Real User Monitoring for React Native apps. Captures screens, taps, HTTP calls, crashes, JS errors, and app performance, and sends them to KloudMate.

Installation

npm install @kloudmate/rum-react-native
cd ios && pod install   # iOS only

The native module links automatically on both platforms. No manual steps.

Expo

This SDK includes native code, so it does not run in Expo Go. Use a development build.

Add the config plugin to your app config:

{
  "expo": {
    "plugins": ["@kloudmate/rum-react-native"]
  }
}

Then create the development build:

npx expo prebuild
npx expo run:android   # or: npx expo run:ios

The plugin registers the native module on Android; iOS needs no extra setup. Works with the New Architecture. Everything else on this page (setup, screens, errors, events) is the same as any React Native app.

Setup

Initialise the SDK once, as early as possible, in your app entry file:

import { init } from '@kloudmate/rum-react-native';

init({
  endpoint: 'https://otel.kloudmate.com:4318',
  rumAccessToken: 'pk_your_public_key',
  applicationName: 'my-app',
  deploymentEnvironment: 'production',
  sessionReplayEnabled: true,
});

Screens, taps, HTTP calls, app start, crashes, and JS errors are captured automatically after this call.

Configuration

| Option | Type | Description | |---|---|---| | endpoint | string | Your KloudMate collector endpoint. Required. | | rumAccessToken | string | Your public RUM key (pk_...). Required. | | applicationName | string | Name your app appears under. Required. | | appId | string | App / bundle id. Defaults to the package name or bundle id. | | deploymentEnvironment | string | e.g. production, staging. | | version | string | Your app version. | | sampleRate | number | Fraction of sessions to record, 0.0–1.0. Default 1.0. | | sessionReplayEnabled | boolean | Record session replay. Default false. | | replaySampleRate | number | Fraction of recorded sessions that also capture replay, 0.0–1.0. Default 1.0. | | captureJsErrors | boolean | Capture uncaught JS errors. Default true. |

TypeScript definitions for the full option list are bundled with the package.

Identify the user

Call after sign in so sessions and errors are attributed to a user:

import { setUser } from '@kloudmate/rum-react-native';

setUser('user-123', '[email protected]');

Screens

React Navigation moves between screens without the native layer noticing, so report the active screen yourself:

import { NavigationContainer } from '@react-navigation/native';
import { setCurrentScreen } from '@kloudmate/rum-react-native';

<NavigationContainer
  onStateChange={(state) => {
    const route = state?.routes?.[state.index];
    if (route) setCurrentScreen(route.name);
  }}
>
  {/* ... */}
</NavigationContainer>

Screens reported this way appear in the Pages and journeys views. Call setCurrentScreen as early as your navigation allows: activity recorded before the first call is not attributed to a screen.

Errors

Uncaught JS errors are captured automatically. To report a handled error:

import { reportError } from '@kloudmate/rum-react-native';

try {
  doWork();
} catch (e) {
  reportError(e);
}

Pass captureJsErrors: false to init if you want to install your own handler instead, then call installJsErrorHandler() when you are ready.

Custom events

import { addEvent } from '@kloudmate/rum-react-native';

addEvent('checkout_completed', { value: 49.99, currency: 'INR' });

Use a constant event name and put the changing parts in the attributes. An attribute named value is treated as a numeric measurement.

Logout

Call endSession() when a user logs out, so the next user does not inherit the previous session:

import { endSession } from '@kloudmate/rum-react-native';

async function logout() {
  endSession();
  await clearAuthState();
}

HTTP capture on Android (optional)

Network requests are captured automatically once you route React Native's HTTP client through the SDK. Add this to your MainApplication (Kotlin), after initialising the SDK, before the app makes its first request:

import com.facebook.react.modules.network.OkHttpClientFactory
import com.facebook.react.modules.network.OkHttpClientProvider
import okhttp3.OkHttpClient

OkHttpClientProvider.setOkHttpClientFactory(OkHttpClientFactory {
    OkHttpClient.Builder()
        .apply { KloudMateRum.okHttpInterceptor()?.let { addInterceptor(it) } }
        .build()
})

API reference

getSessionId and getGlobalAttributes return a Promise; the rest return immediately.

| Function | Description | |---|---| | init(options) | Initialise the SDK. Call once. | | setUser(id, email, extra) | Identify the current user. | | endSession() | Clear the user and start a new session. Call on logout. | | setGlobalAttributes(attrs) | Attach attributes to everything the SDK sends. | | getGlobalAttributes() | Read the current global attributes. | | getSessionId() | Current session id, or null. | | setCurrentScreen(name) | Report the active screen. | | reportFullyDrawn() | Mark the app fully drawn, recording time to first usable screen. | | addEvent(name, attributes) | Record a custom event. | | reportError(error, options) | Report a handled error. Pass { fatal: true } for a crash. | | installJsErrorHandler() | Install the uncaught-JS-error handler manually. |

Limitations

• HTTP requests are not captured on iOS.
• A hang on the JavaScript thread is not detected while the native thread stays responsive.

License

MIT