React Native RUM Collection

React Native RUM Collection

This feature is in open beta. Contact Support to ask questions or to provide feedback on this feature.

Datadog Real User Monitoring (RUM) enables you to visualize and analyze the real-time performance and user journeys of your application’s individual users.

Setup

To install with NPM, run:

npm install dd-sdk-reactnative

To install with Yarn, run:

yarn add dd-sdk-reactnative

Specify application details in UI

  1. In the Datadog app, select UX Monitoring > RUM Applications > New Application.
  2. Choose react-native as your Application Type.
  3. Provide a new application name to generate a unique Datadog application ID and client token.

image

To ensure the safety of your data, you must use a client token. You cannot use only Datadog API keys to configure the dd-sdk-reactnative library, because they would be exposed client-side. For more information about setting up a client token, see the Client Token documentation.

Initialize the library with application context

import { DdSdkReactNative, DdSdkReactNativeConfiguration } from 'dd-sdk-reactnative';


const config = new DdSdkReactNativeConfiguration(
    "<CLIENT_TOKEN>", 
    "<ENVIRONMENT_NAME>", 
    "<RUM_APPLICATION_ID>",
    true, // track User interactions (e.g.: Tap on buttons)
    true, // track XHR Resources
    true // track Errors
)
// Optional: Select your Datadog website (one of "US", "EU" or "GOV")
config.site = "US"
// Optional: enable or disable native crash reports
config.nativeCrashReportEnabled = true
// Optional: sample RUM sessions (here, 80% of session will be sent to Datadog. Default = 100%)
config.sampleRate = 80

DdSdkReactNative.initialize(config)

Track view navigation

Note: Automatic View tracking relies on the React Navigation package. If you use another package to handle navigation in your application, use the manual instrumentation method described below.

To track changes in navigation as RUM Views, set the onready callback of your NavigationContainer component:

import * as React from 'react';
import { DdRumReactNavigationTracking } from 'dd-sdk-reactnative';

function App() {
  const navigationRef = React.useRef(null);
  return (
    <View>
      <NavigationContainer ref={navigationRef} onReady={() => {
        DdRumReactNavigationTracking.startTrackingViews(navigationRef.current)
      }}>
        // …
      </NavigationContainer>
    </View>
  );
}

Note: Only one NavigationContainer can be tracked at the time. If you need to track another container, stop tracking previous one first.

Track custom attributes

You can attach user information to all RUM events to get more detailed information from your RUM sessions.

User information

For user-specific information, use the following code wherever you want in your app (after the SDK has been initialized). The id, name, and email attributes are built into Datadog, and you can add other attributes that makes sense for your app.

DdSdkReactNative.setUser({
    id: "1337", 
    name: "John Smith", 
    email: "john@example.com", 
    type: "premium"
})

Global attributes

You can also keep global attributes to track information about a specific session, such as A/B testing configuration, ad campaign origin, or cart status.

DdSdkReactNative.setAttributes({
    profile_mode: "wall",
    chat_enabled: true,
    campaign_origin: "example_ad_network"
})

Manual instrumentation

If automatic instrumentation doesn’t suit your needs, you can manually create RUM Events and Logs:

import { DdSdkReactNative, DdSdkReactNativeConfiguration, DdLogs, DdRum } from 'dd-sdk-reactnative';

// Initialize the SDK
const config = new DdSdkReactNativeConfiguration(
    "<CLIENT_TOKEN>",
    "<ENVIRONMENT_NAME>",
    "<RUM_APPLICATION_ID>",
    true, // track User interactions (e.g.: Tap on buttons)
    true, // track XHR Resources
    true // track Errors
)
DdSdkReactNative.initialize(config);

// Send logs (use the debug, info, warn or error methods)
DdLogs.debug("Lorem ipsum dolor sit amet…", 0, {});
DdLogs.info("Lorem ipsum dolor sit amet…", 0, {});
DdLogs.warn("Lorem ipsum dolor sit amet…", 0, {});
DdLogs.error("Lorem ipsum dolor sit amet…", 0, {});

// Track RUM Views manually
DdRum.startView('<view-key>', 'View Url', new Date().getTime(), {});
//…
DdRum.stopView('<view-key>', new Date().getTime(), { custom: 42});

// Track RUM Actions manually
DdRum.addAction('TAP', 'button name', new Date().getTime(), {});

// Track RUM Errors manually
DdRum.addError('<message>', 'source', '<stacktrace>', new Date().getTime(), {});


// Track RUM Resource manually
DdRum.startResource('<res-key>', 'GET', 'http://www.example.com/api/v1/test', new Date().getTime(), {} );
//…
DdRum.stopResource('<res-key>', 200, 'xhr', new Date().getTime(), {});

License

Apache License, v2.0

Further Reading