Migrate to the latest React Native SDK

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.

Terminology

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

Dependency

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

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

Instrumentation

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.

Initialization

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'; 
3 
-- Amplitude.getInstance().init(API_KEY) 
5+ init(API_KEY, OPTIONAL_USER_ID, config); 

Configuration

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

logEvent

The logEvent() API maps to track().

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

uploadEvents

The uploadEvents() API maps to flush().

-import { Amplitude } from '@amplitude/react-native'; 
+import { flush } from '@amplitude/analytics-react-native'; 
3 
-Amplitude.getInstance().uploadEvents(); 
+flush(); 

identify

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

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

setUserProperties

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'; 
 3 
 -Amplitude.getInstance().setUserProperties({ 
 -    membership, "paid",
 -    payment, "bank",
 -})
 +const identifyObj = new amplitude.Identify() 
 +identifyObj
 +    .set("membership", "paid")
 +    .set("payment", "bank")
 +amplitude.identify(identifyObj)

clearUserProperties

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'; 
3 
-Amplitude.getInstance().clearUserProperties(); 
+const identifyObj = new amplitude.Identify() 
+identifyObj.clearAll()
+amplitude.identify(identifyObj)

setUserId

The setUserId() API remains the same.

-import { Amplitude } from '@amplitude/react-native'; 
+import { setUserId } from '@amplitude/analytics-react-native' 
3 
-Amplitude.getInstance().setUserId("test_user_id"); 
+setUserId('user@amplitude.com'); 

groupIdentify

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

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

logRevenue

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'; 
 3 
 -const userProperties = { 
 -    price: 3,
 -    productId: 'com.company.productId',
 -    quantity: 2,
 -    revenueType: 'productRevenue',
 -    eventProperties: {
 -        key: 'value',
 -    },
 -};
13 
 -ampInstance.logRevenue(userProperties); 
15 
 +const event = new Revenue() 
 +    .setPrice(3)
 +    .setProductId('com.company.productId')
 +    .setQuantity(2)
 +    .setRevenueType('productRevenue')
 +    .setEventProperties({
 +        key: 'value',
 +    })
24 
 +revenue(event); 

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.

COPPA

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.

1init(API_KEY, OPTIONAL_USER_ID, {
2  migrateLegacyData: false,
3})