React Native SDK Migration Guide

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.

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

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';

- Amplitude.getInstance().init(API_KEY)
+ 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.

Tracking events¶

logEvent()¶

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' });

uploadEvents()¶

The uploadEvents() API maps to flush().

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

- Amplitude.getInstance().uploadEvents();
+ flush();

Set user properties¶

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';

const identifyObj = new Identify();
identifyObj.set('location', 'LAX');

- 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';

- 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';

- 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';

- Amplitude.getInstance().setUserId("test_user_id");
+ setUserId('user@amplitude.com');

Set group properties¶

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';

const groupType = 'plan';
const groupName = 'enterprise';
const identifyObj = new Identify()
identifyObj.set('key1', 'value1');

- Amplitude.getInstance().groupIdentify(groupType, groupName, identifyObj);
+ groupIdentify(groupType, groupName, identifyObj);

Tracking revenue¶

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';

- const userProperties = {
-     price: 3,
-     productId: 'com.company.productId',
-     quantity: 2,
-     revenueType: 'productRevenue',
-     eventProperties: {
-         key: 'value',
-     },
- };

- ampInstance.logRevenue(userProperties);

+ const event = new Revenue()
+     .setPrice(3)
+     .setProductId('com.company.productId')
+     .setQuantity(2)
+     .setRevenueType('productRevenue')
+     .setEventProperties({
+         key: 'value',
+     })

+ revenue(event);

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

Advanced topics¶

Identity¶

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 IDs¶

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.

Comparison¶

This section provides a comparison between different version of SDKs. This overview provides key insights for developers, identifying areas that have significant changes and need careful consideration.

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.

init(API_KEY, OPTIONAL_USER_ID, {
  migrateLegacyData: false,
})