Unified SDK for React Native

The Amplitude Unified SDK for React Native (@amplitude/unified-react-native) installs Analytics, Feature Experiment, Session Replay, and Guides and Surveys through one package and initializes them through one API.

Use the Unified SDK when your app needs multiple Amplitude products with shared configuration. Install the individual product SDKs instead when your app needs only one product or requires independent SDK instances.

The Unified SDK includes:

• Analytics.
• Feature Experiment.
• Session Replay.
• Guides and Surveys.

Install the Unified SDK

The Unified SDK's bundled Guides and Surveys module requires:

• React Native 0.79.2 or later with the New Architecture enabled.
• Android Gradle Plugin 8.7.2 or later and Gradle 8 or later.
• iOS 15 or later and Swift 5.9 or later.

Enable the New Architecture for Android and iOS before you rebuild your app.

npm install @amplitude/unified-react-native

For a bare React Native app, load the package's autolinking preset from your app-level react-native.config.js:

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

If your app already has a React Native configuration, merge the preset's dependencies with your existing configuration:

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

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

The preset lets React Native autolink the native product modules that the Unified SDK installs transitively. You don't need to install those packages directly.

For Android, set newArchEnabled=true in android/gradle.properties. For iOS, follow the New Architecture setup for your React Native version, then install the pods:

cd ios
pod install

Initialize the Unified SDK

Call init() once before you use any product APIs. The method initializes every included product and resolves after initialization finishes.

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

await init("AMPLITUDE_API_KEY");

Initialization is one-shot. Later init() calls return the first initialization promise without reconfiguring or retrying the SDKs. Restart the app before you initialize again after correcting a configuration or native setup problem.

The public SDK APIs don't throw initialization errors. The SDK reports each error through the Analytics loggerProvider. After Analytics initializes, a failure in one product doesn't prevent the remaining products from initializing.

Access SDK features

The Unified SDK exposes the React Native Analytics API and provides accessors for the Experiment client and Session Replay plugin.

import {
  experiment,
  Identify,
  identify,
  sessionReplay,
  track,
} from "@amplitude/unified-react-native";

track("Button Clicked", { buttonName: "Sign Up" });

identify(new Identify().set("plan", "premium"));

const experimentClient = experiment();
await experimentClient?.fetch();
const variant = experimentClient?.variant("experiment-key");

const replayPlugin = sessionReplay();
replayPlugin?.flush();

The package also exports the Analytics helpers Identify, Revenue, and Types, and the AmpMaskView component for Session Replay masking.

Configure the Unified SDK

Pass shared options at the top level and product-specific options in the corresponding product block. Product-specific options override shared options.

import { init, Types } from "@amplitude/unified-react-native";

await init("AMPLITUDE_API_KEY", {
  serverZone: "US",
  instanceName: "app",
  logLevel: Types.LogLevel.Warn,

  analytics: {
    userId: "user-id",
  },
  sessionReplay: {
    sampleRate: 1,
  },
  experiment: {
    deploymentKey: "DEPLOYMENT_KEY",
  },
  engagement: {
    locale: "en-US",
  },
});

Shared options

Product options

• analytics accepts React Native Analytics configuration options.
• experiment accepts React Native Experiment plugin configuration options.
• sessionReplay accepts React Native Session Replay plugin configuration options.
• engagement accepts React Native Guides and Surveys configuration options.

Multiple instances

Use the package-level singleton exports for most apps. The Unified SDK also exports createInstance(), but its clients aren't fully isolated because the React Native Engagement plugin uses a process-wide singleton.

Every client shares the first initialized Engagement plugin and native Engagement instance. The first initialization supplies its API key and Engagement configuration. Later clients can't configure an independent Engagement instance and may update the same shared identity during later boot operations.