---
title: Instrument and configure the Unified SDK for React Native
description: "Configure each product in the Amplitude Unified SDK for React Native, fetch Feature Experiment variants, control Session Replay, and track interactions."
product: analytics
lang: en
last_updated: 2026-11-10
token_estimate: 1878
---
# 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](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure). 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](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/unified-react-native/CHANGELOG.md).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

```ts
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:

| Option | Passed to |
| --- | --- |
| `serverZone` | Analytics, Feature Experiment, Guides and Surveys |
| `instanceName` | Analytics, Feature Experiment |
| `logLevel` | Analytics, Session Replay, Guides and Surveys |

```ts
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.

```ts
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",
  },
});
```

| Block | Accepts |
| --- | --- |
| `analytics` | [React Native SDK options](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/reference#configuration-options) |
| `experiment` | [Experiment React Native options](https://amplitude.com/docs/sdks/experiment-sdks/experiment-react-native#configuration), plus `deploymentKey` |
| `sessionReplay` | [Session Replay options](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/reference#sessionreplay-options) |
| `engagement` | [Guides and Surveys React Native options](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-rn-sdk#configuration-options) |

## 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()`:

```ts
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](https://amplitude.com/docs/sdks/experiment-sdks/experiment-react-native).

### 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:

```ts
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()`:

```ts
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`.

```ts
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`:

```tsx
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](https://amplitude.com/docs/sdks/session-replay/session-replay-react-native-sdk-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](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-rn-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.

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

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

The [Babel plugin](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#wrap-handlers-with-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.

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