Instrument and configure the Unified SDK for React Native

This page covers what's specific to the Unified SDK for React Native: configuring each product, and using Feature Experiment, Session Replay, and Guides and Surveys through one package. For tracking, identity, sessions, Autocapture, and data delivery, go to Instrument and configure the React Native SDK. Every analytics method there works the same when you import it from @amplitude/unified-react-native. For changes between versions, go to the @amplitude/unified-react-native changelog.

import * as amplitude from "@amplitude/unified-react-native";

Configure each product

How init sets up each product

init(apiKey, options) runs these steps once:

1. Initializes Analytics with the top-level options and options.analytics. If this fails, init() stops and the other products don't load.
2. Adds Feature Experiment, Session Replay, and Guides and Surveys as analytics plugins, in parallel. A failure in one doesn't stop the others.
3. Starts the Experiment client, which fetches flags, and boots Guides and Surveys with the current user ID and device ID.

Every product shares the analytics identity. Experiment, for example, sees the same user ID and device ID as your events.

Set shared options at the top level

Three options apply to more than one product:

await amplitude.init("AMPLITUDE_API_KEY", {
  serverZone: "EU",
  logLevel: amplitude.Types.LogLevel.Warn,
});

Pass options to each product

Product options go in a block named for the product. A value in a product block overrides the top-level value for that product.

await amplitude.init("AMPLITUDE_API_KEY", {
  serverZone: "EU",
  analytics: {
    autocapture: true,
    userId: "user-12345",
  },
  experiment: {
    deploymentKey: "DEPLOYMENT_KEY",
  },
  sessionReplay: {
    sampleRate: 0.1,
  },
  engagement: {
    locale: "en-US",
  },
});

Use Feature Experiment

Fetch flags and read a variant

init() starts the Experiment client, which fetches flags for the current user. After init() resolves, read variants through experiment():

await amplitude.init("AMPLITUDE_API_KEY", {
  experiment: { deploymentKey: "DEPLOYMENT_KEY" },
});

const experimentClient = amplitude.experiment();
const variant = experimentClient?.variant("checkout-redesign");

if (variant?.value === "treatment") {
  // Show the new checkout.
}

experiment() returns undefined until init() finishes. After the user ID changes, call await experimentClient?.fetch() to get that user's variants. For the client's other methods, go to the Experiment React Native SDK.

Set the deployment key

Without experiment.deploymentKey, the SDK uses your analytics API key as the deployment key. Set a client deployment key from the same project. With the wrong key, the log shows Failed to initialize Experiment. Flags error response: status=401.

Use Session Replay

Choose a sample rate

Session Replay records nothing by default, because sampleRate defaults to 0. Set it between 0 and 1, the share of sessions to record:

await amplitude.init("AMPLITUDE_API_KEY", {
  sessionReplay: { sampleRate: 0.1 }, // Records 10% of sessions.
});

With enableRemoteConfig on (the default), Session Replay also fetches its settings from Amplitude.

Control recording from code

sessionReplay() returns the Session Replay plugin after init() finishes, or undefined if Session Replay failed to install. To record only on some screens, set autoStart: false and call start() and stop():

await amplitude.init("AMPLITUDE_API_KEY", {
  sessionReplay: { sampleRate: 1, autoStart: false },
});

await amplitude.sessionReplay()?.start();
// ...
await amplitude.sessionReplay()?.stop();

Mask sensitive content

Set the default masking level with privacyConfig.maskLevel: light, medium (default), or conservative.

await amplitude.init("AMPLITUDE_API_KEY", {
  sessionReplay: {
    sampleRate: 0.1,
    privacyConfig: { maskLevel: "conservative" },
  },
});

To mask, unmask, or block one part of the screen, wrap it in AmpMaskView:

import { AmpMaskView } from "@amplitude/unified-react-native";

<AmpMaskView mask="amp-mask">
  <Text>{user.email}</Text>
</AmpMaskView>;

mask takes amp-mask, amp-unmask, or amp-block. For details, go to the Session Replay React Native plugin.

Use Guides and Surveys

The Unified SDK boots Guides and Surveys during init(). Pass its options, such as locale, in engagement. To show guides and surveys, follow the screen tracking and other steps in the Guides and Surveys React Native SDK documentation.

Track element interactions

The Unified SDK doesn't export ampCapture(). Import it from @amplitude/analytics-react-native, which the Unified SDK installs. ampCapture() calls reach the Unified SDK's analytics instance.

import { ampCapture } from "@amplitude/analytics-react-native";

<Button title="Buy" onPress={ampCapture(onBuy, { action: "Press", testID: "buy" })} />;

The Babel plugin adds the same import. Some package managers, such as pnpm by default, don't let app code import transitive dependencies. In that case, make @amplitude/analytics-react-native importable, for example with public-hoist-pattern. Don't initialize @amplitude/analytics-react-native yourself.

Run more than one instance

Use the package-level functions for most apps. createInstance() returns another client, but clients aren't fully independent: an app has only one Guides and Surveys plugin. Every client shares the first initialized Guides and Surveys plugin, with that client's API key and engagement options.

const secondary = amplitude.createInstance();
await secondary.init("OTHER_API_KEY", {
  instanceName: "secondary",
});