---
title: Get started with the React Native SDK
description: "Install the Amplitude React Native SDK, initialize it, send a first event, and fix the native linking and upload problems that stop events from arriving."
product: analytics
lang: en
last_updated: 2026-11-10
token_estimate: 2489
---
# Get started with the React Native SDK

- **Package:** `@amplitude/analytics-react-native` ([npm](https://www.npmjs.com/package/@amplitude/analytics-react-native))
- **Latest version:** 1.13.1

This guide installs the React Native SDK (`@amplitude/analytics-react-native`), initializes it, and sends one custom event to Amplitude. Each step lists the problems that commonly break that step, so you can fix each problem where it happens. For the full option list, go to [Configuration options](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/reference#configuration-options). For changes between versions, go to the [React Native SDK release notes](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk-release-notes).

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

The React Native SDK is the analytics-only package. If you also need Session Replay, Feature Experiment, or Guides and Surveys, install the [Unified SDK for React Native](https://amplitude.com/docs/sdks/analytics/react-native/unified-sdk/get-started) (`@amplitude/unified-react-native`) instead. It includes this SDK, so don't install both as direct dependencies.

## Prerequisites

- An Amplitude project and its API key. Find the key in _Settings > Projects > your project > General_.
- The data center your organization uses: US (default) or EU.
- A React Native app for iOS, Android, or the web (react-native-web). React Native doesn't keep backward compatibility between releases, so check the React Native CLI [compatibility list](https://github.com/react-native-community/cli#compatibility) before you upgrade.
- React Native 0.68 or later, Gradle 7.5.1 or later, and Android Gradle Plugin 7.2.1 or later. These are the minimums SDK 1.4.0 and later build with. Amplitude support covers the latest React Native version only. For older SDK versions, go to [Platform support](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/reference#platform-support).
- iOS 12.0 or later, and Android API level 21 or later. These are the minimums the SDK's native modules declare. Your React Native version can require higher ones.

## Install the SDK

The SDK stores identity and unsent events in `@react-native-async-storage/async-storage`, so install that package too. To use a different storage backend, go to [Store data somewhere other than AsyncStorage](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#store-data-somewhere-other-than-asyncstorage).

#### npm

```bash
npm install @amplitude/analytics-react-native @react-native-async-storage/async-storage
cd ios && pod install
```

#### yarn

```bash
yarn add @amplitude/analytics-react-native @react-native-async-storage/async-storage
cd ios && pod install
```

#### Expo

```bash
npx expo install @amplitude/analytics-react-native @react-native-async-storage/async-storage
```

The SDK includes native code, so it needs a [development build](https://docs.expo.dev/develop/development-builds/introduction/). It doesn't run in Expo Go.

Then import the package:

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

The SDK has native modules for iOS and Android. If you ship over-the-air (OTA) updates, for example with Expo EAS Update, publish a new native build when you upgrade across a release that changed native code. Go to [Platform support](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/reference#platform-support) for those releases.

### Fix installation problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Events have no `os_name`, `device_model`, or `carrier`, and `platform` is `Web` on a phone | The SDK's native module isn't linked, so the SDK falls back to web context. | Run `pod install`, rebuild the app, and use a development build instead of Expo Go. |
| Android build fails after you add the SDK | Gradle or the Android Gradle Plugin is older than the SDK supports. | Upgrade to Gradle 7.5.1 or later and Android Gradle Plugin 7.2.1 or later. |
| Native behavior differs between builds that ship the same JavaScript | An OTA update changed the SDK's JavaScript without the native code from the same release. | Publish a new native build. Go to [Platform support](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/reference#platform-support). |

## Initialize the SDK

Call `init()` once, as early as possible, for example at the top of your app's entry file. The SDK queues calls you make before `init()` finishes and runs them in order afterward.

```ts
amplitude.init("AMPLITUDE_API_KEY");
```

Pass a user ID as the second argument when you already know it. Pass options as the third argument. To pass options without a user ID, set the second argument to `undefined`:

```ts
amplitude.init("AMPLITUDE_API_KEY", "user-12345", {
  autocapture: true,
});

amplitude.init("AMPLITUDE_API_KEY", undefined, {
  autocapture: true,
});
```

If your project uses the EU data center, set `serverZone`:

```ts
amplitude.init("AMPLITUDE_API_KEY", undefined, {
  serverZone: "EU",
});
```

Autocapture is off by default. `autocapture: true` turns on sessions, application lifecycles, screen views, element interactions, frustration interactions, and network tracking. For each feature, go to [Autocapture](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#autocapture).

### Fix initialization problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| Options seem ignored, and `user_id` on events is an object such as `{"serverZone":"EU"}` | You passed options as the second argument. The second argument is the user ID. | Pass options third: `init(apiKey, undefined, options)`. |
| Events go to the wrong region, or ingestion returns `Invalid API key` | `serverZone` doesn't match the project's data center. | Set `serverZone: "EU"` for EU projects. Omit it for US projects. |
| A new device ID on every app launch, and unsent events lost on restart | AsyncStorage isn't installed or linked. The SDK doesn't throw. It keeps identity and the event queue in memory instead. | Install `@react-native-async-storage/async-storage`, run `pod install`, and rebuild the app. Or pass your own `cookieStorage` and `storageProvider`. |
| Log warning: `Network connectivity checker plugin found no connectivity source; defaulting to online.` | The SDK's connectivity native module isn't linked, so the SDK can't detect offline periods. | Rebuild the app after `pod install`. Without the module, the SDK still sends events but doesn't pause uploads offline. |

## Send a first event

Track one custom event and wait for the upload result. `track()` returns an object whose `promise` resolves after the SDK finishes 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"
```

The SDK uploads queued events about one second after the first one enters the queue, in requests of up to 30 events, so expect about one second of delay.

### Fix upload problems

| `result.code` and `result.message` | Cause | Fix |
| --- | --- | --- |
| `0`, `Event skipped due to optOut config` | Opt-out is on for this device. The SDK stores opt-out with identity, so it persists across app launches. | Call `amplitude.setOptOut(false)`. |
| `0`, `Event skipped due to empty event type` | The event name is empty. | Pass a non-empty string as the first argument. |
| `400`, `Event rejected due to missing API key` | `init()` received an empty API key. | Check the variable that holds your key. A missing environment variable often becomes an empty string at build time. |
| `400`, `Invalid API key: ...` | The key is wrong, or belongs to a project in the other data center. | Copy the key again and check `serverZone`. |
| `500`, `Event rejected due to exceeded retry count` | The request never succeeded, and the SDK gave up after `flushMaxRetries` (5) attempts. No network, a blocked host, or server errors cause this. | Check the device's connection and any proxy or firewall between the device and `api2.amplitude.com` (or `api.eu.amplitude.com`). Go to [Verify events](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/verify-events#check-what-the-sdk-sent). |
| The promise never resolves | `init()` never ran on this instance, or the device is offline and the SDK is holding the event until it reconnects. | Make sure `init()` runs on the same instance. Check connectivity. |

## Confirm the event in Amplitude

1. In Amplitude, open _User Lookup_ and search for the user ID you passed, 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/react-native-sdk/verify-events). That page walks through each stage between `track()` and Amplitude's servers.

## Next steps

- Identify signed-in users with [`setUserId()`](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#set-the-user-id), and call `reset()` when they sign out.
- Track screens with [React Navigation](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#screen-views).
- Choose which [Autocapture](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#autocapture) events to turn on.
- Add the custom events and properties your tracking plan needs. Go to [Track events](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk/instrument-and-configure#track-events).