--- title: React Native SDK description: "Reference for the current React Native SDK with installation, configuration, and platform support." product: analytics lang: en last_updated: 2026-10-22 token_estimate: 16349 --- # React Native SDK > 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`. - **Package:** `@amplitude/analytics-react-native` ([npm](https://www.npmjs.com/package/@amplitude/analytics-react-native)) - **Latest version:** 1.12.4 The React Native SDK lets you send events to Amplitude. > **Note:** React Native support > > [React-Native](https://github.com/facebook/react-native) doesn't provide stable release versioning, which makes backward compatibility challenging. React-Native itself isn't backward compatible and can introduce breaking changes across versions. Check the React-Native [compatibility list](https://github.com/react-native-community/cli#compatibility) for more details. Amplitude supports only the latest version of React-Native. ## Compatibility matrix The following matrix lists Amplitude React Native SDK support for [different versions of React Native and React Native CLI](https://github.com/react-native-community/cli). | @amplitude/analytics-react-native | react-native | Gradle | Android Gradle Plugin | | --- | --- | --- | --- | | >= 1.4.0 | >= 0.68 | 7.5.1+ | 7.2.1+ | | >= 1.0.0, <= 1.3.6 | >= 0.61, <= 0.70 | 3.5.3+ | 3.5.3+ | Learn more about the Android [Gradle Plugin compatibility](https://developer.android.com/studio/releases/gradle-plugin#updating-gradle). ## Install the SDK To start using the Amplitude React Native SDK, install the package to your project with npm. The SDK uses `@react-native-async-storage/async-storage` by default to persist identity and the event queue across app launches, so install it alongside the SDK. If you'd rather use your own storage backend, refer to [Opt out of AsyncStorage](#opt-out-of-asyncstorage). > **Tip:** Web and Expo support > > You can use this SDK for react-native apps built for web or built using [Expo](https://expo.dev/) (Expo Go not yet supported). #### npm ```bash npm install @amplitude/analytics-react-native npm install @react-native-async-storage/async-storage ``` #### yarn ```bash yarn add @amplitude/analytics-react-native yarn add @react-native-async-storage/async-storage ``` #### expo ```bash expo install @amplitude/analytics-react-native expo install @react-native-async-storage/async-storage ``` Install the native modules to run the SDK on iOS. ```bash cd ios pod install ``` ## Initialize the SDK Initialize the SDK before any instrumentation. The API key for your Amplitude project is required. You can optionally pass a user ID and config object in this call. After you initialize the SDK, you can use it anywhere in your application. ```ts import { init } from "@amplitude/analytics-react-native"; // Option 1, initialize with API_KEY only init(API_KEY); // Option 2, initialize including user ID if it's already known init(API_KEY, "user@amplitude.com"); // Option 3, initialize including configuration init(API_KEY, "user@amplitude.com", { disableCookies: true, // Disables the use of browser cookies }); ``` ## Configure the SDK > **Note:** Web vs. mobile > > The SDK shares configuration across web and mobile platforms. Many of these options don't apply when you run the SDK on native platforms like iOS or Android. For example, on web, the SDK stores identity in the browser cookie by default. On native platforms, the SDK stores identity in async storage. #### Configuration options | Name | Description | Default Value | | --- | --- | --- | | `instanceName` | `string`. The instance name. | `$default_instance` | | `flushIntervalMillis` | `number`. Sets the interval for uploading events to Amplitude in milliseconds. | 1,000 (1 second) | | `flushQueueSize` | `number`. Sets the maximum number of events that the SDK batches in a single upload attempt. | 30 events | | `flushMaxRetries` | `number`. Sets the maximum number of retries for failed upload attempts. Only applies to retryable errors. | 5 times. | | `offline` | `boolean` | `OfflineDisabled`. Whether the device has a network connection. The SDK detects connectivity automatically and queues events while the device is offline. Refer to [Offline mode](#offline-mode). | `false` | | `logLevel` | `LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`. Sets the log level. | `LogLevel.Warn` | | `loggerProvider ` | `Logger`. Sets a custom `loggerProvider` class from the Logger to emit log messages to your chosen destination. | `Amplitude Logger` | | `minIdLength` | `number`. Sets the minimum length for the value of `userId` and `deviceId` properties. | `5` | | `optOut` | `boolean`. Sets permission to track events. Setting a value of `true` prevents Amplitude from tracking and uploading events. | `false` | | `serverUrl` | `string`. Sets the URL where the SDK uploads events. | `https://api2.amplitude.com/2/httpapi` | | `serverZone` | `EU` or `US`. Sets the Amplitude server zone. Set this to `EU` for Amplitude projects created in `EU` data center. | `US` | | `useBatch` | `boolean`. Sets whether to upload events to Batch API instead of the default HTTP V2 API. | `false` | | `appVersion` | `string`. Sets an app version for events tracked. This can be the version of your application. For example: "1.0.0" | `undefined` | | `deviceId` | `string`. Sets an identifier for the device running your application. | `UUID()` | | `cookieExpiration` | `number`. Sets expiration of cookies created in days. | 365 days | | `cookieSameSite` | `string`. Sets `SameSite` property of cookies created. | `Lax` | | `cookieSecure` | `boolean`. Sets `Secure` property of cookies created. | `false` | | `cookieStorage` | `Storage`. Sets a custom implementation of `Storage` to persist user identity. | `MemoryStorage` | | `cookieUpgrade` | `boolean`. Sets upgrading from cookies created by [maintenance Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk). If true, the new Browser SDK deletes cookies created by the maintenance Browser SDK. If false, the Browser SDK keeps cookies created by the maintenance Browser SDK. | `true` | | `disableCookies` | `boolean`. Sets permission to use cookies. If value is `true`, the SDK uses the localStorage API to persist user identity. | Cookies enabled by default. | | `domain` | `string`. Sets the domain property of cookies created. | `undefined` | | `partnerId` | `string`. Sets partner ID. Amplitude requires the customer who built an event ingestion integration to add the partner identifier to `partner_id`. | `undefined` | | `sessionTimeout` | `number`. Sets the period of inactivity from the last tracked event before a session expires in milliseconds. | 1,800,000 milliseconds (30 minutes) | | `userId` | `number`. Sets an identifier for the tracked user. Must have a minimum length of 5 characters unless overridden with the `minIdLength` option. | `undefined` | | `trackingOptions` | `TrackingOptions`. Configures tracking of additional properties. Refer to the `Optional tracking` section for more information. | All tracking options enabled by default. | | `storageProvider` | `Storage`. Implements a custom `storageProvider` class from Storage. | `MemoryStorage` | | `trackingSessionEvents` | `boolean`. Whether the SDK automatically logs start and end session events that correspond to the start and end of a user's session. Prefer `autocapture.sessions` when you use Autocapture. | `false` | | `autocapture` | `boolean` | `ReactNativeAutocaptureOptions`. Available in `1.6.8`+. Configures Autocapture tracking. Refer to [Autocapture](#autocapture). | Autocapture disabled by default. | | `migrateLegacyData` | `boolean`. Available in `1.3.4`+. Whether to migrate [maintenance SDK](https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk-maintenance) data (events, user/device ID). | `true` | ### Configure batching behavior To support high-performance environments, the SDK sends events in batches. The `track` method queues every event in memory. The SDK flushes events in batches in the background. You can customize batch behavior with `flushQueueSize` and `flushIntervalMillis`. By default, the serverUrl is `https://api2.amplitude.com/2/httpapi`. To send large batches of data at a time, set `useBatch` to `true` to set `setServerUrl` to the batch event upload API `https://api2.amplitude.com/batch`. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals. ```ts import * as amplitude from "@amplitude/analytics-react-native"; amplitude.init(API_KEY, OPTIONAL_USER_ID, { // Events queued in memory will flush when number of events exceed upload threshold // Default value is 30 flushQueueSize: 50, // Events queue will flush every certain milliseconds based on setting // Default value is 10000 milliseconds flushIntervalMillis: 20000, }); ``` ### Offline mode Beginning with version 1.6.0, the React Native SDK supports offline mode. The SDK detects when the device loses network connectivity and queues events instead of dropping them. While the device is offline, the SDK persists tracked events to storage and stops attempting uploads. When the device reconnects, the SDK flushes the queued events to Amplitude. Offline mode is on by default, so you don't need to configure it. The SDK detects connectivity through a native module: `NWPathMonitor` on iOS and `ConnectivityManager` on Android. On web (react-native-web), the SDK uses the browser's `navigator.onLine` state and `online` and `offline` events. The SDK persists events to storage while the device is offline, so the configured `storageProvider` bounds the size of the offline queue. Refer to [Opt out of AsyncStorage](#opt-out-of-asyncstorage) to change where the SDK stores queued events. #### Native module setup Connectivity detection relies on the SDK's native modules: - iOS: The native module links automatically when you run `pod install`. Refer to [Install the SDK](#install-the-sdk). The minimum supported iOS deployment target is 13.0. - Android: The SDK declares the `ACCESS_NETWORK_STATE` permission in its manifest, which merges into your app's manifest automatically. You don't need to make any manual changes. #### Disable offline mode To turn off automatic connectivity detection, set `offline` to `OfflineDisabled` when you initialize the SDK. ```ts import * as amplitude from "@amplitude/analytics-react-native"; amplitude.init(API_KEY, OPTIONAL_USER_ID, { offline: amplitude.Types.OfflineDisabled, }); ``` When you disable offline mode, the SDK flushes events based on `flushIntervalMillis` and `flushQueueSize` only. To implement your own offline logic, disable offline mode as shown, then toggle `config.offline` based on your own network detection. ### EU data residency You can configure the server zone when you initialize the client to send data to Amplitude's EU servers. The SDK sends data based on the server zone if you set it. > **Note:** > > For EU data residency, set up the project inside Amplitude EU. You must initialize the SDK with the API key from Amplitude EU. ```ts amplitude.init(API_KEY, OPTIONAL_USER_ID, { serverZone: "EU", }); ``` ### Debugging You can control the level of logs printed to the developer console. - 'None': Suppresses all log messages. - 'Error': Shows error messages only. - 'Warn': Shows error messages and warnings. This is the default value if you don't explicitly specify `logLevel`. - 'Verbose': Shows informative messages. - 'Debug': Shows error messages, warnings, and informative messages that may help with debugging, including the function context information for all SDK public method invocations. Use this logging mode only in development phases. Set the log level by configuring the `logLevel` with the level you want. ```ts amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, { logLevel: amplitude.Types.LogLevel.Warn, }); ``` The default logger outputs logs to the developer console. You can provide your own logger implementation based on the `Logger` interface for customization. For example, you can collect error messages from the SDK in a production environment. Set the logger by configuring the `loggerProvider` with your own implementation. ```ts amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, { loggerProvider: new MyLogger(), }); ``` #### Debug mode Enable the debug mode by setting the `logLevel` to "Debug", for example: ```ts amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, { logLevel: amplitude.Types.LogLevel.Debug, }); ``` The default logger outputs extra function context information to the developer console when you invoke any SDK public method, including: - 'type': Category of this context, for example "invoke public method". - 'name': Name of the invoked function, for example "track". - 'args': Arguments of the invoked function. - 'stacktrace': Stacktrace of the invoked function. - 'time': Start and end timestamp of the function invocation. - 'states': Useful internal states snapshot before and after the function invocation. ## Autocapture Available in `@amplitude/analytics-react-native` 1.6.8 and later. Autocapture lets you track sessions, application lifecycle events, screen views, element interactions, frustration interactions, and network requests with minimal instrumentation. The React Native SDK autocaptures the following event types when you enable them: - Sessions (`session_start` and `session_end`) - Application lifecycles (`[Amplitude] Application Opened` and `[Amplitude] Application Backgrounded`) - Screen views (`[Amplitude] Screen Viewed`), when you call the screen view helpers - Element interactions (`[Amplitude] Element Pressed`), when you enable element interactions and wrap handlers (manually or with the Babel plugin) - Frustration interactions (`[Amplitude] Rage Click` and `[Amplitude] Error Click`), when you enable frustration interactions and wrap handlers (manually or with the Babel plugin) - Network requests (`[Amplitude] Network Request`), when you enable network tracking #### Autocapture options | Name | Description | | --- | --- | | `config.autocapture.sessions` | Optional. Type: `boolean`. Enables or disables session start and session end events. When `true`, Amplitude tracks the same session events as `trackingSessionEvents: true`. Default when you pass `autocapture: true`: `true`. | | `config.autocapture.appLifecycles` | Optional. Type: `boolean`. Enables or disables application opened and backgrounded events. Default when you pass `autocapture: true`: `true`. | | `config.autocapture.screenViews` | Optional. Type: `boolean`. Set to `false` to disable `trackScreenView` and `trackScreenViewOnNavigationStateChange`. Omitting this option or setting it to `true` leaves the helpers enabled. Screen views aren't automatic: wire the helpers into your navigator. | | `config.autocapture.elementInteractions` | Optional. Type: `boolean`. Enables or disables element interaction tracking. When `true`, Amplitude tracks interactions on handlers wrapped with `ampCapture`. Use the Babel plugin to wrap handlers at compile time, or wrap them in source. Default value is `false`. | | `config.autocapture.frustrationInteractions` | Optional. Type: `boolean` or object. Enables or disables frustration interaction tracking. When `true`, Amplitude tracks rage clicks and error clicks on handlers wrapped with `ampCapture`. To turn one type off, pass `{ rageClick: boolean, errorClick: boolean }`. Both types stay on unless you set that field to `false`. Default value is `false`. Default when you pass `autocapture: true`: `true`. Available in `1.11.0` and later. Error clicks require `1.12.0` or later. Refer to [Track frustration interactions](#track-frustration-interactions) for more information. | | `config.autocapture.networkTracking` | Optional. Type: `boolean`. Enables or disables capturing network request events invoked by [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) and [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). If `true`, Amplitude tracks failed network requests. To configure what Amplitude captures, set this as a network tracking options object. Default value is `false`. Default when you pass `autocapture: true`: `true`. Refer to [Track network requests](#track-network-requests) for more information and configuration options. | ### Enable Autocapture Pass `autocapture: true` to enable sessions, app lifecycles, screen views, element interactions, frustration interactions, and network tracking together, or pass an options object to choose features. ```ts import { init } from "@amplitude/analytics-react-native"; // Enable every Autocapture feature init(API_KEY, OPTIONAL_USER_ID, { autocapture: true, }); // Or enable features individually init(API_KEY, OPTIONAL_USER_ID, { autocapture: { sessions: true, appLifecycles: true, networkTracking: true, }, }); ``` To turn Autocapture off, omit `autocapture` or set it to `false`. ```ts init(API_KEY, OPTIONAL_USER_ID, { autocapture: false, }); ``` ### Track sessions Set `autocapture.sessions` to `true` (or pass `autocapture: true`) to track `session_start` and `session_end` when the session ID changes. This matches `trackingSessionEvents: true`. Prefer the Autocapture option for new instrumentation. ```ts init(API_KEY, OPTIONAL_USER_ID, { autocapture: { sessions: true, }, }); ``` > **Note:** > > `trackingSessionEvents` still works. Use `autocapture.sessions` when you adopt Autocapture. ### Track application lifecycles Set `autocapture.appLifecycles` to `true` to track application foreground and background events from React Native `AppState`. ```ts init(API_KEY, OPTIONAL_USER_ID, { autocapture: { appLifecycles: true, }, }); ``` When you enable this setting, Amplitude tracks: - `[Amplitude] Application Opened`: fires on cold start when the app is already active at init, and again when the app returns to the foreground after a real background. - `[Amplitude] Application Backgrounded`: fires when `AppState` changes to `background`. > **Note:** > > The SDK doesn't treat `inactive` → `active` (for example, Control Center) as a new open. It emits `[Amplitude] Application Opened` only after a prior background. ### Track screen views Screen view Autocapture isn't fully automatic. Call `trackScreenView` or `trackScreenViewOnNavigationStateChange` to send `[Amplitude] Screen Viewed` with `[Amplitude] Screen Name`. Set `autocapture.screenViews` to `false` only when you want to disable those helpers. ```ts import { init, trackScreenView, trackScreenViewOnNavigationStateChange, } from "@amplitude/analytics-react-native"; import { NavigationContainer, useNavigationContainerRef, } from "@react-navigation/native"; init(API_KEY, OPTIONAL_USER_ID, { autocapture: { sessions: true, appLifecycles: true, }, }); // Manual screen view trackScreenView("Home"); // React Navigation: onStateChange doesn't fire for the initial route; // call the helper from onReady for the cold-start screen. function App() { const navigationRef = useNavigationContainerRef(); return ( { trackScreenViewOnNavigationStateChange(navigationRef.getRootState()); }} onStateChange={trackScreenViewOnNavigationStateChange} > {/* navigators */} ); } ``` `trackScreenViewOnNavigationStateChange` resolves the focused leaf route in nested navigators and skips duplicate callbacks for the same screen name (for example, `onReady` plus `onStateChange`, or param-only updates). Re-init and `reset` clear the dedupe state. ### Track element interactions Set `autocapture.elementInteractions` to `true` so Amplitude tracks UI interactions on handlers wrapped with `ampCapture`. When a wrapped handler runs, the SDK sends `[Amplitude] Element Pressed` with properties such as `[Amplitude] Target Test ID`, `[Amplitude] Target Accessibility Label`, `[Amplitude] Target Component`, `[Amplitude] Target Element`, and `[Amplitude] Action`. ```ts import { init } from "@amplitude/analytics-react-native"; init(API_KEY, OPTIONAL_USER_ID, { autocapture: { elementInteractions: true, }, }); ``` You can wrap handlers in source with `ampCapture`, or use the Babel plugin so Metro/Babel wraps them at compile time. ```tsx import { ampCapture } from "@amplitude/analytics-react-native";