Migrate to the latest React Native SDK

SDK Comparison


Latest React Native SDK

Maintenance React Native SDK





Mobile platforms (Android & iOS) utilize native app context modules for accessing system info, async storage for persistence.

Wrapper of the iOS and Android SDK and Amplitude JavaScript SDK. Providing mappings from React Native to native SDK functions.

Supported platforms

iOS, Android, Web and Expo.

iOS, Android, Web.


Configuration is implemented by Configuration object during initialize amplitude.

Supports specific setter methods.

Storage provider

LocalStorage() by default, if not enabled, use MemoryStorage(). Fully configurable.

Depends on the Maintenance iOS, Maintenance Android and Maintenance Browser SDK storage.

Logger provider

Amplitude Logger. Fully customizable.

Depends on the native iOS, Android, Amplitude JavaScript logger provider.




Server endpoint



Amplitude's latest React Native SDK (@amplitude/analytics-react-native) features a plugin architecture, built-in type definition and broader platform support.

The latest React Native SDK isn't fully backwards compatible with maintenance React Native SDK @amplitude/react-native. However, it will transfer user, device, and event data to the new SDK automatically in versions v1.3.4 and above.

To migrate to @amplitude/analytics-react-native, update your dependencies and instrumentation.


  • @amplitude/react-native: Maintenance React Native SDK
  • @amplitude/analytics-react-native: Latest React Native SDK


Update package.json to uninstall the maintenance React Native SDK and install the latest React Native SDK.

2 "dependencies": {
- "@amplitude/react-native": "*"
+ "@amplitude/analytics-react-native": "^1"
5 }


Latest React Native SDK offers an API to instrument events. To migrate to it, you need to update a few calls. The following sections detail which calls have changed.


getInstance() in the maintenance SDK only accepts API key and has been removed. To initialize the SDK, call init(), with the user ID and configuration parameters.

-- import { Amplitude } from '@amplitude/react-native';
++ import { init } from '@amplitude/analytics-react-native';
-- Amplitude.getInstance().init(API_KEY)
5+ init(API_KEY, OPTIONAL_USER_ID, config);


The latest React Native SDK instance accepts a configuration object during upon initialization that contains similar settings to the maintenance SDK.

@amplitude/react-native @amplitude/analytics-react-native
enableCoppaControl() Refer to COPPA section for more details
disableCoppaControl() Refer to COPPA section for more details
setAdvertisingIdForDeviceId() No configuration to set ADID as device ID. But ADID is still tracked by default as config.trackingOptions.adid defaults to true. To learn more about how device ID is initialized here.
setAppSetIdForDeviceId() No configuration to set App Set ID as device ID. But the latest React Native SDK will track it in a newly released version soon.
setOptOut() both setOptOut() and config.optOut are supported
trackingSessionEvents() config.trackingSessionEvents
setUseDynamicConfig() NOT SUPPORTED
setMinTimeBetweenSessionsMillis() config.sessionTimeout
setServerZone() config.serverZone
setServerUrl() config.serverUrl
setEventUploadMaxBatchSize() config.flushQueueSize
setEventUploadPeriodMillis() config.flushIntervalMillis
setEventUploadThreshold() config.flushQueueSize
enableLogging() Logging is enabled and cannot be turned off. However, you can set config.logLevel and customize config.loggerProvider
setLogLevel() config.logLevel
addLogCallback() It's not fully supported but you can customize a logger by setting config.loggerProvider.


The logEvent() API maps to track().

-import { Amplitude } from '@amplitude/react-native';
+import { track } from '@amplitude/analytics-react-native';
-Amplitude.getInstance().logEvent('Button Clicked', {buttonColor: 'primary'});
+track('Button Clicked', { buttonColor: 'primary' });


The uploadEvents() API maps to flush().

-import { Amplitude } from '@amplitude/react-native';
+import { flush } from '@amplitude/analytics-react-native';


The identify() API and Identify type remain the same.

-import { Amplitude, Identify } from '@amplitude/react-native';
+import { Identify, identify } from '@amplitude/analytics-react-native';
4const identifyObj = new Identify();
5identifyObj.set('location', 'LAX');


The setUserProperties() API has been removed, but you can now use the unified identify() API to add user properties.

-import { Amplitude } from '@amplitude/react-native';
+import { Identify, identify } from '@amplitude/analytics-react-native';
- membership, "paid",
- payment, "bank",
+const identifyObj = new amplitude.Identify()
+ .set("membership", "paid")
+ .set("payment", "bank")


The clearUserProperties() API has been removed, but you can now use the unified identify() API to remove user properties.

-import { Amplitude } from '@amplitude/react-native';
+import { Identify, identify } from '@amplitude/analytics-react-native';
+const identifyObj = new amplitude.Identify()



The maintenance SDK uses an old SDK endpoint (api2.amplitude.com) which enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength to a smaller value if you allowed identifiers with fewer than 5 characters.

The setUserId() API remains the same.

-import { Amplitude } from '@amplitude/react-native';
+import { setUserId } from '@amplitude/analytics-react-native'


You can now make an identify call without calling getInstance().

-import { Amplitude } from '@amplitude/react-native';
+import { Identify, groupIdentify } from '@amplitude/analytics-react-native';
4const groupType = 'plan';
5const groupName = 'enterprise';
6const identifyObj = new Identify()
7identifyObj.set('key1', 'value1');
-Amplitude.getInstance().groupIdentify(groupType, groupName, identifyObj);
+groupIdentify(groupType, groupName, identifyObj);


The logRevenue() API maps to revenue(). receipt and receiptSignature is not supported.

-import { Amplitude } from '@amplitude/react-native';
+import { Revenue, revenue } from '@amplitude/analytics-react-native';
-const userProperties = {
- price: 3,
- productId: 'com.company.productId',
- quantity: 2,
- revenueType: 'productRevenue',
- eventProperties: {
- key: 'value',
- },
+const event = new Revenue()
+ .setPrice(3)
+ .setProductId('com.company.productId')
+ .setQuantity(2)
+ .setRevenueType('productRevenue')
+ .setEventProperties({
+ key: 'value',
+ })

You can also use setRevenue(6) instead of setPrice(3) and setQuantity(2).

Advanced topics

Device ID

As the maintenance React Native SDK is a wrapper of the maintenance iOS, maintenance Android SDK and maintenance Browser SDK and provides mappings from React Native to native SDK functions, device ID generation follows the native SDK of each platform. Learn more about device ID lifecycle of maintenance iOS SDK and maintenance Android SDK. You can also call setAdvertisingIdForDeviceId() or setAppSetIdForDeviceId() to set ADID or App Set ID as device ID.

The latest React Native SDK initializes the device ID in the following order, with the device ID being set to the first valid value encountered:

  1. Device ID of in the configuration on initialization
  2. "deviceId" value from URL param, for example http://example.com/?deviceId=123456789. If it runs on Web.
  3. Device ID in cookie storage.
  4. A randomly generated 36-character UUID

Advertising ID

The maintenance React Native SDK supports setting an advertising ID as device ID by setAdvertisingIdForDeviceId() or setAppSetIdForDeviceId(). The latest React Native SDK tracks ADID by default as config.trackingOptions.adid defaults to true. However, the latest React Native SDK doesn't support App Set ID, IDFA, or IDFV.


You can enable COPPA control by enableCoppaControl() in maintenance React Native SDK. The latest React Native SDK doesn't support that API but you can still enable COPPA using config.trackingOptions or an Enrichment Plugin to remove identifying information from being tracked.

  • Learn how to enable IDFA, IDFV, ADID, and AppSetId in the Advertising Identifiers documentation.
  • You can turn off IP address tracking by setting config.trackingOptions.ipAddress to false
  • You can use an enrichment Plugin to delete city in the payload, or any other identifying information.
  • Location (latitude and longitude) isn't tracked

Session events

The maintenance React Native SDK supports automatically log start and end events by calling trackingSessionEvents(true). In the latest React Native SDK, you can do the same by setting config.trackingSessionEvents to true. Events logged within the same session have the same session ID and Amplitude groups events together by session.

Data migration

Starting v1.3.4, existing maintenance SDK data (events, user/device ID) are moved to the latest SDK by default. It can be disabled by setting migrateLegacyData to false in the Configuration.

2 migrateLegacyData: false,
Was this page helpful?

Thanks for your feedback!

June 18th, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.