React Native SDK observability reference

Overview

This topic documents how to get started with the LaunchDarkly observability plugin for the React Native SDK.

The React Native SDK supports the observability plugin for error monitoring, logging, and tracing, and the session replay plugin for capturing screen recordings of user sessions.

Prerequisites and dependencies

This reference guide assumes you are familiar with the LaunchDarkly React Native SDK.

The observability plugin requires React Native SDK version 10.10.0 or later.

The React Native SDK version 10.x is compatible with Expo. Only iOS and Android platforms are supported. Web is not supported.

Supported React Native and Expo versions

The LaunchDarkly observability and session replay plugins for React Native target the following React Native and Expo versions:

Not all React Native and Expo versions have been explicitly tested with the observability and session replay plugins, as both are in Early Access. New React Native and Expo releases are expected to work; if you run into an issue, please file an issue on GitHub.

Get started

Follow these steps to get started:

• Install the plugin
• Initialize the React Native SDK client
• Configure the plugin options
• Configure session replay
• Explore supported features
• Review observability data in LaunchDarkly

Install the plugin

LaunchDarkly uses a plugin to the React Native SDK to provide observability.

The first step is to make both the SDK and the observability plugin available as dependencies.

Here’s how:

$
 npm install @launchdarkly/react-native-client-sdk
$
 npm install @launchdarkly/observability-react-native

Then, import the plugin into your code:

1
import { ReactNativeLDClient } from '@launchdarkly/react-native-client-sdk';
2
import { Observability, LDObserve } from '@launchdarkly/observability-react-native';

Initialize the client

Next, initialize the SDK and the plugin.

To initialize, you need your LaunchDarkly environment’s mobile key. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client and identify a context in the React Native SDK reference guide.

Here’s how to initialize the SDK and plugin:

1
const client = new ReactNativeLDClient(
2
    'example-mobile-key',
3
    AutoEnvAttributes.Enabled,
4
    {
5
      plugins: [
6
        new Observability()
7
      ],
8
    }
9
);

Configure the plugin options

You can configure options for the observability plugin when you initialize the SDK. The plugin constructor takes an optional object with the configuration details.

Here is an example:

1
const client = new ReactNativeLDClient(
2
    'example-mobile-key',
3
    AutoEnvAttributes.Enabled,
4
    {
5
      plugins: [
6
        new Observability({
7
          serviceName: 'example-service',
8
          // we recommend setting service_version to the latest deployed git SHA
9
          serviceVersion: 'example-sha'
10
        })
11
      ],
12
    }
13
);

For more information on plugin options, read Configuration for client-side observability.

Configure session replay

Session replay captures screen recordings of user interactions to help you understand how users interact with your application. Session replay is delivered as a separate plugin, @launchdarkly/session-replay-react-native, that works alongside the observability plugin.

Session replay for React Native is supported on iOS and Android.

Install the session replay plugin

Add the session replay package as a dependency alongside the observability plugin:

$
npm install @launchdarkly/session-replay-react-native

After installing, run the iOS pod install step so that CocoaPods pulls in the native LaunchDarklyObservability and LaunchDarklySessionReplay frameworks:

$
cd ios && pod install

Then, import the plugin into your code:

1
import { createSessionReplayPlugin } from '@launchdarkly/session-replay-react-native';

Initialize session replay

To enable session replay, create the session replay plugin and add it to the plugins list passed to ReactNativeLDClient. You can use session replay on its own, or alongside the observability plugin.

1
import {
2
  ReactNativeLDClient,
3
  AutoEnvAttributes,
4
} from '@launchdarkly/react-native-client-sdk';
5
import { Observability } from '@launchdarkly/observability-react-native';
6
import { createSessionReplayPlugin } from '@launchdarkly/session-replay-react-native';
7
8
const sessionReplay = createSessionReplayPlugin({
9
  isEnabled: true,
10
  maskTextInputs: true,
11
  maskWebViews: true,
12
  maskLabels: true,
13
  maskImages: true,
14
  maskTestIDs: ['password', 'ssn'],
15
});
16
17
const client = new ReactNativeLDClient(
18
  'example-mobile-key',
19
  AutoEnvAttributes.Enabled,
20
  {
21
    plugins: [
22
      new Observability({ serviceName: 'example-service' }),
23
      sessionReplay,
24
    ],
25
  }
26
);

Initialize session replay manually

You can initialize the session replay plugin manually, after the SDK client is initialized. This approach is useful for feature-flagged rollouts, or for deferring data collection until after you have received end user consent.

Set isEnabled to false in the plugin options, then call startSessionReplay() when you are ready to begin recording.

As an alternative to registering session replay as a plugin, you can control it imperatively. You use the lower-level configureSessionReplay() and startSessionReplay() functions without registering a plugin at all.

1
import { createSessionReplayPlugin, startSessionReplay, stopSessionReplay } from '@launchdarkly/session-replay-react-native';
2
3
const sessionReplay = createSessionReplayPlugin({
4
  isEnabled: false, // don't start recording automatically
5
  maskTextInputs: true,
6
});
7
8
const client = new ReactNativeLDClient(
9
  'example-mobile-key',
10
  AutoEnvAttributes.Enabled,
11
  { plugins: [sessionReplay] }
12
);
13
14
// Later, after user consent or a feature flag check:
15
await startSessionReplay();
16
17
// To stop recording:
18
await stopSessionReplay();

This approach allows you to:

• Feature-flag the rollout of session replay to a subset of end users
• Wait for end user consent before starting data collection
• Dynamically enable session replay based on runtime conditions
• Maintain compliance with privacy regulations

Configure session replay privacy options

The session replay plugin provides several privacy controls that decide whether each view is captured. Pass them to createSessionReplayPlugin or configureSessionReplay.

How the SDK decides what to mask

For each view, the SDK evaluates the following rules in order and stops at the first that applies:

1. Explicit masking (highest priority): The view, or any of its ancestors, is wrapped in <LDMask> or has a testID matched by maskTestIDs. The view is masked.
2. Explicit unmasking: The view, or any of its ancestors, is wrapped in <LDUnmask> or has a testID matched by unmaskTestIDs. The view is unmasked.
3. Global configuration: The global privacy options (maskTextInputs, maskLabels, maskImages, maskWebViews) apply.

If two rules conflict at the same level, masking takes precedence over unmasking. An ancestor <LDMask> overrides any <LDUnmask> further down the tree.

Global toggles by component type

Each global toggle affects every instance of the corresponding React Native component across your app, on both iOS and Android.

1
const sessionReplay = createSessionReplayPlugin({
2
  isEnabled: true,
3
  maskTextInputs: true, // default — masks every <TextInput>
4
  maskLabels: false,    // when true, masks every <Text>
5
  maskImages: false,    // when true, masks every <Image>
6
  maskWebViews: false,  // when true, masks every <WebView>
7
});

Mask or unmask views by testID

Use maskTestIDs and unmaskTestIDs to target specific views by their testID property. Matches use exact string equality, so 'password' matches <View testID="password" /> but not <View testID="password_field" />. Both options work on iOS and Android.

1
const sessionReplay = createSessionReplayPlugin({
2
  maskTestIDs: ['password', 'ssn'],
3
  unmaskTestIDs: ['greeting'],
4
});

Mask or unmask a subtree with <LDMask> and <LDUnmask>

Use the <LDMask> and <LDUnmask> wrapper components to redact a subtree without giving it a testID. <LDMask> propagates to all descendants. After you wrap a subtree in <LDMask>, nothing inside it can opt out of masking.

1
import { LDMask, LDUnmask } from '@launchdarkly/session-replay-react-native';
2
3
<LDMask>
4
  <Text>account balance: $1,234</Text>
5
</LDMask>;
6
7
<LDUnmask>
8
  <Text>display even when maskLabels is on</Text>
9
</LDUnmask>;

Session replay configuration options

The SessionReplayOptions object supports the following parameters:

• isEnabled: Controls whether recording starts automatically when the plugin registers. Defaults to true. Set to false to start recording manually with startSessionReplay().
• serviceName: The service name used for session replay telemetry. Defaults to "sessionreplay-react-native".
• maskTextInputs: Masks all <TextInput> components. Defaults to true.
• maskWebViews: Masks the contents of <WebView> components. When enabled, web views are rendered as blank rectangles in session replays. Defaults to false.
• maskLabels: Masks all <Text> components. Defaults to false.
• maskImages: Masks all <Image> components. Defaults to false.
• maskTestIDs: Masks an array of testID values. Matches use exact string equality. Applied on iOS and Android.
• unmaskTestIDs: Excludes an array of testID values from masking. Matches use exact string equality. Applied on iOS and Android.
• minimumAlpha: Minimum alpha value for view visibility in recordings. Views with alpha below this threshold are not captured. Defaults to 0.02. iOS only.

For more information on session replay configuration, read Configuration for session replay.

Explore supported features

The observability plugin supports the following features. After the SDK and plugins are initialized, you can access these from within your application:

• Configuration for client-side observability
• Configuration for session replay
• Errors
• Logs
• Metrics
• Tracing

Review observability data in LaunchDarkly

After you initialize the SDK and observability plugin, your application automatically starts sending observability data back to LaunchDarkly, including errors and logs. You can review this information in the LaunchDarkly user interface. To learn how, read Observability.