Mobile RUM - React Native SDK

The Middleware React Native RUM SDK collects user activity, performance data, and errors across iOS and Android applications. It connects JavaScript and native application activity with the sessions in which problems occur.

Collected data includes app startup, navigation, network requests, JavaScript errors, and native crashes. Session Replay helps explain what the user experienced—for example, a failed request that prevented navigation to the next screen.

Prerequisites#

Before installing the SDK, make sure you have:

• React Native 0.68 or later.
• A Middleware account and RUM application credentials.
• Access to your React Native application source code.
• HTTPS connectivity to the Middleware ingestion endpoint.

For SDK 2.x, the native platform requirements are:

Note: On iOS, MiddlewareRum is a static framework. If your project uses use_frameworks!, ensure dependent pods use static linking.

Installation#

1yarn add @middleware.io/middleware-react-native

1npm install @middleware.io/middleware-react-native

1cd ios
2pod install
3cd ..

1import React from 'react';
2import {
3  MiddlewareWrapper,
4  type ReactNativeConfiguration,
5} from '@middleware.io/middleware-react-native';
6
7import App from './App';
8
9const middlewareConfig: ReactNativeConfiguration = {
10  serviceName: 'my-react-native-app',
11  projectName: 'My-React-Native-App',
12  accountKey: '<MW_API_KEY>',
13  target: 'https://<MW_UID>.middleware.io',
14  deploymentEnvironment: 'PROD',
15
16  globalAttributes: {
17    'app.version': '1.0.0',
18  },
19};
20
21export default function Root() {
22  return (
23    <MiddlewareWrapper config={middlewareConfig}>
24      <App />
25    </MiddlewareWrapper>
26  );
27}

Optional configuration#

Configure network monitoring#

Network instrumentation is enabled by default for requests made through fetch and XMLHttpRequest.

The SDK captures request methods, URLs, response status codes, timings, and selected headers.

You can exclude specific URLs or headers from collection:

1const middlewareConfig: ReactNativeConfiguration = {
2  serviceName: 'my-react-native-app',
3  projectName: 'My-React-Native-App',
4  accountKey: '<MW_API_KEY>',
5  target: 'https://<MW_UID>.middleware.io',
6
7  ignoreUrls: [
8    /\/api\/health/,
9    /\/api\/internal\/.*/,
10  ],
11
12  ignoreHeaders: new Set([
13    'x-internal-header',
14  ]),
15};

The SDK always masks the value of the x-access-token header.

To disable network instrumentation entirely, add:

1networkInstrumentation: false

Note: Network libraries that bypass the global fetch or XHR implementation may require separate instrumentation.

Configure Session Replay#

Session Replay is enabled by default and starts automatically when the SDK initializes.

It records native screen activity and connects recordings with navigation, errors, and network requests.

Configure recording quality and privacy#

Add recordingOptions to your SDK configuration:

1const middlewareConfig: ReactNativeConfiguration = {
2  serviceName: 'my-react-native-app',
3  projectName: 'My-React-Native-App',
4  accountKey: '<MW_API_KEY>',
5  target: 'https://<MW_UID>.middleware.io',
6
7  sessionRecording: true,
8
9  recordingOptions: {
10    frequency: 'standard',
11    quality: 'standard',
12    maskAllTextInputs: true,
13    maskAllImages: true,
14  },
15};

Disable Session Replay#

To collect RUM telemetry without recording user sessions:

1sessionRecording: false

Session recording limits#

• Maximum session duration: 4 hours.
• Idle timeout: 15 minutes.
• Default: Session Replay enabled.

A new session starts when activity resumes after the idle timeout.

Mask sensitive information#

The SDK masks text inputs and images by default.

To mask additional UI elements, wrap sensitive components with MiddlewareSanitizedView:

1import {
2  MiddlewareSanitizedView,
3} from '@middleware.io/middleware-react-native';
4
5function PaymentScreen() {
6  return (
7    <MiddlewareSanitizedView>
8      <PaymentDetails />
9    </MiddlewareSanitizedView>
10  );
11}

Use this for payment information, authentication screens, OTP fields, or other sensitive UI elements.

Masking happens on the device before recording data is uploaded.

Privacy recommendation: Review sensitive screens before enabling Session Replay in production. Avoid sending passwords, tokens, or personal information through custom attributes and logs.

Configure distributed tracing#

Distributed tracing connects React Native network requests with backend APM traces.

By default, the SDK injects W3C traceparent and B3 tracing headers into supported HTTP requests.

Prerequisites#

• Middleware APM instrumentation must be enabled on backend services.
• Backend services must support W3C Trace Context or B3 propagation.
• Network instrumentation must be enabled.

Restrict trace propagation targets#

To send tracing headers only to your backend APIs:

1const middlewareConfig: ReactNativeConfiguration = {
2  serviceName: 'my-react-native-app',
3  projectName: 'My-React-Native-App',
4  accountKey: '<MW_API_KEY>',
5  target: 'https://<MW_UID>.middleware.io',
6
7  tracePropagationTargets: [
8    /api\.example\.com/,
9    /checkout\.example\.com/,
10  ],
11
12  tracePropagationFormat: 'w3c',
13};

Requests to other domains are still monitored but do not receive trace propagation headers.

Use regular expressions for matching domains. Plain string entries must match the complete URL exactly.

To disable trace propagation, set:

1tracePropagationTargets: []

Verify trace correlation#

1. Open your application and trigger a backend API request.
2. Go to RUM → Session Explorer.
3. Open the session and select the network request.
4. Follow the associated backend trace.

If the request contains a trace ID but no backend spans, verify that the backend has APM instrumentation and supports the configured propagation format.

Add custom logs and errors#

Custom logs#

Use MiddlewareRum to record application-specific logs:

1import {
2  MiddlewareRum,
3} from '@middleware.io/middleware-react-native';
4
5MiddlewareRum.debug('Loading checkout');
6MiddlewareRum.info('Payment initiated');
7MiddlewareRum.warn('API response delayed');
8MiddlewareRum.error('Payment request failed');

These logs provide additional context when investigating user sessions.

Report handled exceptions#

JavaScript errors and native crashes are captured automatically.

For handled exceptions, use reportError():

1try {
2  throw new Error('Payment request failed');
3} catch (error) {
4  MiddlewareRum.reportError(error as Error);
5}

Add custom attributes#

Use global attributes to filter sessions by application version, environment, or user group.

Set attributes during initialization:

1globalAttributes: {
2  'app.version': '1.0.0',
3  'user.type': 'premium',
4}

To update attributes after initialization:

1MiddlewareRum.setGlobalAttributes({
2  'app.version': '1.0.1',
3  'user.type': 'premium',
4});

Prefer stable, non-sensitive attributes.

Configure session sampling#

Use sessionSamplingRatio to control the percentage of sessions collected:

1sessionSamplingRatio: 0.5

The value ranges from 0.0 to 1.0.

Sampling applies to session traces and recordings.

Configuration reference#

All options accepted by ReactNativeConfiguration:

Troubleshooting#

No RUM data appears#

If the application runs but telemetry does not appear:

• Verify that the SDK is installed and native dependencies are linked.
• Confirm that MiddlewareWrapper is initialized at the application root.
• Check the API key and target URL.
• Verify that the device can connect to Middleware over HTTPS.
• Enable debug: true to review SDK diagnostic logs.

Network requests are missing#

If sessions appear but HTTP requests are not captured:

• Confirm that networkInstrumentation is enabled.
• Verify that requests use fetch or XMLHttpRequest.
• Check whether the URLs match an ignoreUrls rule.
• Check whether a networking library bypasses the global HTTP implementation.

Navigation changes are not tracked#

• Keep NavigationContainer inside MiddlewareWrapper.
• Confirm that your application uses a supported React Navigation setup.
• Verify that screen transitions update the navigation state.

Session Replay is missing#

• Confirm that sessionRecording is not set to false.
• Verify that the application remains active long enough to generate a recording.
• Check that the session is not excluded by sampling.
• Review SDK diagnostic logs for recording errors.

Sensitive information appears in recordings#

• Verify that maskAllTextInputs and maskAllImages are enabled.
• Wrap sensitive components with MiddlewareSanitizedView.
• Review custom attributes and logs for sensitive values.

Backend traces are not correlated#

• Verify that backend APM instrumentation is enabled.
• Confirm that tracePropagationTargets matches the requested backend URL.
• Check that the backend accepts the configured propagation format.
• Ensure that tracing headers are not removed by gateways or proxies.

iOS or Android build errors#

For iOS:#

• Run cd ios && pod install.
• Verify that the deployment target is iOS 13 or later.
• Check static framework linking if use_frameworks! is enabled.

For Android:#

• Verify that compileSdk is 35 or later.
• Confirm that Kotlin Gradle Plugin 2.0+ is configured.
• Ensure core library desugaring is enabled.
• Rebuild the Android project after installing the SDK.

If the issue persists, contact Middleware Support at [email protected].