@mobore/rum-react-native

React Native SDK for RUM Mobile Observability.

Installation

This package requires the following native dependencies:

• @react-native-community/netinfo
• react-native-device-info

You can install them along with the package:

For vanilla React Native (using npm):

npm install @mobore/rum-react-native @react-native-community/netinfo react-native-device-info

For Expo projects:

expo install @mobore/rum-react-native @react-native-community/netinfo react-native-device-info

Expo Compatibility

This package relies on native code, which means it's not compatible with Expo Go. You'll need to use a custom development client. After installing the dependencies, you may need to generate the native project files before running:

npx expo prebuild

Then run your app on a simulator or device:

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

Usage

Initialization

Initialize the RUM SDK as early as possible in your application's lifecycle. The easiest way is to use the RumProvider component which wraps your application.

Using RumProvider (Recommended)

The RumProvider enables automatic instrumentation of views, errors, and network requests. For automatic view tracking to work, you need to provide a ref to your NavigationContainer.

Example with React Navigation:

// App.tsx
import { RumProvider } from '@mobore/rum-react-native';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';

export default function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    // The RumProvider needs the navigation ref to track screen views.
    <RumProvider
      config={{
        clientToken: "YOUR_CLIENT_TOKEN",
      }}
      ref={navigationRef}
    >
      <NavigationContainer ref={navigationRef}>
        {/* Your application's navigators and screens */}
      </NavigationContainer>
    </RumProvider>
  );
}

Example with Expo Router:

If you're using Expo Router, you can wrap your root layout. Expo Router's layout components automatically handle the ref.

// app/_layout.tsx
import { RumProvider } from '@mobore/rum-react-native';
import { useNavigationContainerRef } from 'expo-router';

export default function RootLayout() {
  const navigationRef = useNavigationContainerRef();

  return (
    <RumProvider
      config={{
        clientToken: "YOUR_CLIENT_TOKEN",
      }}
      ref={navigationRef}
    >
      {/* Your application's components */}
    </RumProvider>
  );
}

This will auto enable tracing views, errors, network request.

Alternatively, for manual initialization without the RumProvider component:

import RUM, { AutoInstrumentation } from '@mobore/rum-react-native';

RUM.initialize({
  clientToken: 'YOUR_CLIENT_TOKEN',
}).then(() => {
  // Start auto-instrumentation for navigation and errors
  AutoInstrumentation.start();
});

Manual View Tracking

Track screen views manually, useful for single-page applications or when automatic tracking is insufficient.

import RUM from '@mobore/rum-react-native';

// Start a view
RUM.startView('HomeScreen');

Track Actions

Record user interactions or custom actions within your application. This is useful for tracking things like button clicks, form submissions, or other important events.

Example with a React Native Button:

import { Button } from 'react-native';
import RUM from '@mobore/rum-react-native';

function PurScreen() {
  const handlePurchase = () => {
    // ... purchase logic ...

    // Track the purchase action
    RUM.addAction('Purchase Completed', {
      actionType: 'click',
      attributes: {
        productId: 'abc-456',
        price: 19.99,
        currency: 'USD',
      },
    });
  };

  return (
    <Button title="Purchase" onPress={handlePurchase} />
  );
}

You can also add actions without a specific user interaction:

import RUM from '@mobore/rum-react-native';

RUM.addAction('Loaded User From Cache', { actionType: 'custom' });

// You can also pass a context to addAction
const currentContext = RUM.getCurrentContext();
RUM.addAction(currentContext, 'Item Added to Cart');

Track Errors

Manually report errors to RUM, alongside automatic crash reporting.

import RUM from '@mobore/rum-react-native';

try {
  // Some code that might throw an error
  throw new Error('Something went wrong!');
} catch (error) {
  RUM.addError(error, 'frontend_logic');
}

// You can also track string errors
RUM.addError('Failed to load data', 'network_request');

// You can also pass a context to addError
const currentContext = RUM.getCurrentContext();
RUM.addError(currentContext, 'Error with context', 'custom_context_error');