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. For changes between versions, go to the @amplitude/unified-react-native changelog.

The Unified SDK bundles the React Native SDK (@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 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. The products include native code, so the SDK doesn't run in Expo Go.

Install the SDK

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

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:

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:

cd ios && pod install

Fix installation problems

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.

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

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.

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

Next steps

• Set shared and per-product options. Go to Configure each product.
• Fetch flags and read variants. Go to Use Feature Experiment.
• Choose a Session Replay sample rate and mask sensitive views. Go to Use Session Replay.
• Track custom events, identify users, and choose Autocapture events. Go to Instrument and configure the React Native SDK.