---
title: Get started with the Unified SDK for React Native
description: "Install the Amplitude Unified SDK for React Native, initialize Analytics, Feature Experiment, Session Replay, and Guides and Surveys with one call, and send a first event."
product: analytics
lang: en
last_updated: 2026-11-10
token_estimate: 2069
---
# Get started with the Unified SDK for React Native

Install the Unified SDK for React Native (`@amplitude/unified-react-native`), initialize every product it includes with one call, and send one custom event to Amplitude. For the full option list, go to [UnifiedOptions](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/reference#unifiedoptions). 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`.

> **Note:** Beta
>
> The Unified SDK for React Native is in beta. Its version numbers end in `-beta`, and its API can change between beta releases.

The Unified SDK bundles the [React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/get-started) (`@amplitude/analytics-react-native`) with Feature Experiment, Session Replay, and Guides and Surveys. Every analytics method and option works the same as in the React Native SDK. If you need Analytics only, install the React Native SDK instead. Don't add both packages as direct dependencies.

## Prerequisites

- An Amplitude project and its API key. To find the key, go to _Settings > Projects_, select your project, and open the _General_ tab.
- The data center your organization uses: US (default) or EU.
- React Native 0.76 or later. The bundled [Guides and Surveys SDK](https://amplitude.com/docs/sdks/guides-and-surveys/guides-and-surveys-rn-sdk) needs more:

  - React Native 0.79.2 or later, with the New Architecture turned on.
  - Android Gradle Plugin 8.7.2 or later, and Gradle 8 or later.
  - iOS 15 or later, and Swift 5.9 or later.
- A bare React Native app, or an Expo app with a [development build](https://docs.expo.dev/develop/development-builds/introduction/). The products include native code, so the SDK doesn't run in Expo Go.

## Install the SDK

#### npm

```bash
npm install @amplitude/unified-react-native
```

#### yarn

```bash
yarn add @amplitude/unified-react-native
```

#### Expo

```bash
npx expo install @amplitude/unified-react-native
```

The package installs each product's native module as a dependency of its own. React Native autolinks only packages listed in your app's `package.json`, so load the package's autolinking preset from your app's `react-native.config.js`:

```js
module.exports = require("@amplitude/unified-react-native/react-native.config");
```

If you already have a `react-native.config.js`, merge the preset's `dependencies` into it:

```js
const amplitude = require("@amplitude/unified-react-native/react-native.config");

module.exports = {
  // Your existing configuration
  dependencies: {
    ...amplitude.dependencies,
    // Your existing dependency overrides
  },
};
```

The preset links these packages: `@amplitude/analytics-react-native`, `@amplitude/experiment-react-native-client`, `@amplitude/plugin-session-replay-react-native`, `@amplitude/plugin-engagement-react-native`, and `@react-native-async-storage/async-storage`. You don't install them yourself.

Turn on the New Architecture (on Android, set `newArchEnabled=true` in `android/gradle.properties`), then install pods and rebuild the app:

```bash
cd ios && pod install
```

### Fix installation problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Log: `Failed to initialize Session Replay. The package '@amplitude/plugin-session-replay-react-native' doesn't seem to be linked.` | The native modules aren't linked. | Add the autolinking preset to `react-native.config.js`, run `pod install`, and rebuild. Don't use Expo Go. |
| Events have no `os_name` or `device_model`, and `platform` is `Web` on a phone | The analytics native module isn't linked. | Same fix: add the preset, run `pod install`, and rebuild. |
| iOS or Android build fails in the Guides and Surveys module | React Native, the New Architecture, Gradle, or the iOS target is below what Guides and Surveys needs. | Meet the versions in [Prerequisites](#prerequisites). |
| Events sent twice, or two device IDs | The app initializes both this package and `@amplitude/analytics-react-native`. | Keep one Amplitude entry point. Import every analytics call from `@amplitude/unified-react-native`. |

## Initialize the SDK

Call `init()` once, as early as possible. It initializes Analytics, then adds Feature Experiment, Session Replay, and Guides and Surveys. The returned promise resolves when every product finishes.

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

await amplitude.init("AMPLITUDE_API_KEY", {
  serverZone: "EU", // Omit for US projects.
  analytics: { autocapture: true },
  sessionReplay: { sampleRate: 1 }, // Records every session. Lower this before production.
});
```

`init()` takes options as its second argument. It has no user ID argument. Pass `analytics.userId`, or call `setUserId()` afterward. Analytics calls you make before `init()` finishes wait in a queue and run afterward.

`init()` is one-shot. Later calls return the first call's promise and change nothing, even with a different API key or options. To apply a fix to your configuration, restart the app.

`init()` doesn't throw. It reports each product's failure through the analytics logger as `Failed to initialize <product>.` If Analytics fails, the SDK skips the other products. If one of the other products fails, the rest still initialize.

### Fix initialization problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Log: `Failed to initialize Experiment. Flags error response: status=401` | The deployment key is wrong. Without `experiment.deploymentKey`, the SDK uses the API key. | Set `experiment.deploymentKey` to a client deployment key from the same project. |
| A second `init()` call has no effect | `init()` is one-shot. | Call it once. Restart the app after you change options. |
| EU project, but Guides and Surveys uses US servers | `serverZone` appears only inside `analytics`. Guides and Surveys reads only the top-level value or its own. | Set `serverZone` at the top level, where every product reads it. |
| No replays | `sessionReplay.sampleRate` is `0`, the default. | Set `sampleRate` above `0`. |

## Send a first event

Track one custom event and wait for the upload result. `track()` returns an object whose `promise` resolves after the upload attempt.

```ts
const result = await amplitude.track("Sign Up Clicked", {
  plan: "starter",
}).promise;

console.log(result.code, result.message);
// 200 "Event tracked successfully"
```

### Fix upload problems

The Unified SDK uploads events through the bundled React Native SDK, so the result codes match. For every `result.code` and `result.message`, go to [Fix upload problems](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/get-started#fix-upload-problems) in the React Native SDK.

## Confirm the event in Amplitude

1. In Amplitude, open **User Lookup** and search for the user ID you set, or for the device ID from `amplitude.getDeviceId()`.
2. Open the **Activity** tab and turn on **Live event updates**.
3. Confirm that `Sign Up Clicked` appears with the `plan` property.

If the event doesn't appear within a minute, follow [Verify events](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/verify-events).

## Next steps

- Set shared and per-product options. Go to [Configure each product](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/instrument-and-configure#configure-each-product).
- Fetch flags and read variants. Go to [Use Feature Experiment](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/instrument-and-configure#use-feature-experiment).
- Choose a Session Replay sample rate and mask sensitive views. Go to [Use Session Replay](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/instrument-and-configure#use-session-replay).
- Track custom events, identify users, and choose Autocapture events. Go to [Instrument and configure the React Native SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure).