Manually instrument React Native applications

Manually instrument React Native applications to collect additional telemetry, sanitize personally identifiable information, add global attributes, and more.

You can manually instrument React Native applications using the Splunk RUM React Native agent to collect additional telemetry, add global attributes, and more.

Manage global attributes

Global attributes are key-value pairs added to all reported data. Global attributes are useful for reporting application- or user-specific values as tags. The following examples show how to define global attributes:

  • To add metadata during agent initialization:

    TYPESCRIPT 
    <SplunkRumProvider
  agentConfiguration={{
    endpoint: {
      realm: 'your-splunk-realm',
      rumAccessToken: 'your-splunk-rum-access-token',
    },
    appName: 'your-application-name',
    deploymentEnvironment: 'your-environment-name',
    globalAttributes: {
      'app.region': 'us-east',
      'app.build': 123,
    },
  }}
>
  <AppRoot />
</SplunkRumProvider>

  • To add metadata after agent initialization:

    TYPESCRIPT 
    import { SplunkRum } from '@splunk/otel-react-native';

const attrs = SplunkRum.instance.globalAttributes;

await attrs.setString('user.id', '123');
await attrs.setNumber('cart.items', 3);
await attrs.setAllInNamespace('device', {
  model: 'iPhone',
  os: 'iOS',
});

Track users

By default, the Splunk RUM React Native agent uses NO_TRACKING. To activate anonymous user tracking:

TYPESCRIPT 
import { SplunkRum } from '@splunk/otel-react-native';

await SplunkRum.instance.user.preferences.setTrackingMode('ANONYMOUS_TRACKING');

Report custom events and workflows

You can report custom events and workflows happening in your application using the trackCustomEvent and trackWorkflow APIs. Additionally, you have the option to set custom attributes. See example below:

TYPESCRIPT 
import { SplunkRum } from '@splunk/otel-react-native';

await SplunkRum.instance.customTracking.trackCustomEvent('checkout_complete', {
  'order.total': 99.99,
  'order.items': 3,
});

The following example shows how to start a workflow for which metrics are recorded by Splunk RUM:

TYPESCRIPT 
const workflow = await SplunkRum.instance.customTracking.startWorkflow('checkout');
// ... perform checkout steps ...
await workflow.end();

Get agent and session state

You can inspect the current state of the agent and the active session:

TYPESCRIPT 
const state = await SplunkRum.instance.getState();
const session = await SplunkRum.instance.session.state();

WebView integration (browser RUM correlation)

Use SplunkWebView to integrate browser RUM running inside a WebView with the native RUM session:

TYPESCRIPT 
import { WebView } from 'react-native-webview';
import { SplunkWebView } from '@splunk/otel-react-native';

<SplunkWebView
  WebViewComponent={WebView}
  source={{ uri: 'https://example.com' }}
/>;

For manual integration, call integrateWebViewWithBrowserRum once you have the native view tag:

TYPESCRIPT 
import { WebView } from 'react-native-webview';
import { SplunkRum } from '@splunk/otel-react-native';

const webViewRef = useRef<WebView>(null);

const onLoadEnd = () => {
  const nativeRef = (webViewRef.current as any)?.webViewRef?.current;
  const viewTag = nativeRef?._nativeTag;
  if (viewTag) {
    SplunkRum.instance.integrateWebViewWithBrowserRum(viewTag);
  }
};

<WebView
  ref={webViewRef}
  onLoadEnd={onLoadEnd}
  source={{ uri: 'https://example.com' }}
/>;

Automatic navigation detection

Automatic navigation detection is deactivated by default. You can activate it by configuring the Navigation detection module (detection of screen names) module.

Manually track navigation events

By default, the Splunk RUM React Native agent does not automatically track navigation events. If you enable automatic navigation tracking, the agent monitors native navigation components:

  • Android: Activity and Fragment lifecycle events. This might not work for UI frameworks such as Jetpack Compose, which use different lifecycle patterns.
  • iOS: UIKit view-controller lifecycle callbacks. The agent observes show and transition notifications to open and close spans and derives screen names from the controller type. This approach depends on UIKit-driven controller transitions and does not work for UI stacks such as pure SwiftUI.

Because automatic tracking does not support all navigation patterns, manual tracking is recommended for scenarios such as:

  • Custom routers
  • Unnamed routes
  • Tab changes
  • Unsupported navigation flows

To manually track a screen, call SplunkRum.instance.navigation.track():

CODE 
SplunkRum.instance.navigation.track('Screen name');

This sends a navigation span to Splunk RUM and associates the specified screen name with subsequent spans.

You can also include optional attributes when tracking a screen:

JSON 
await SplunkRum.instance.navigation.track('Checkout', {
  'checkout.type': 'express',
});

Manual tracking reports a navigation event and updates screen.name for subsequent RUM telemetry.

Add server trace context from Splunk APM

The Splunk RUM React Native agent collects server trace context using back-end data provided by Splunk APM instrumentation through the Server-Timing header. In some cases, you might want to generate the header manually.

To create the Server-Timing header manually, provide a Server-Timing header with the name traceparent, where the desc field holds the version, the trace ID, the parent ID, and the trace flag.

Consider the following HTTP header:

CODE 
Server-Timing: traceparent;desc="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"

The example resolves to a context containing the following data:

CODE 
version=00 trace-id=4bf92f3577b34da6a3ce929d0e0e4736parent-id=00f067aa0ba902b7 trace-flags=01

When generating a value for the traceparent header, make sure that it matches the following regular expression:

CODE 
00-([0-9a-f]{32})-([0-9a-f]{16})-01

Server timing headers with values that don't match the pattern are automatically discarded. For more information, see the Server-Timing and traceparent documentation on the W3C website.

If multiple valid Server-Timing headers are found, the last valid one is used.