Migrate to the latest React Native SDK

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

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

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.

json

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

Instrumentation

The latest React Native SDK offers an API to instrument events. To migrate, update the following calls.

Initialization

The maintenance SDK's getInstance() method only accepts an API key, and the latest SDK removes it. 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 accepts a configuration object on initialization with settings similar to the maintenance SDK.

@amplitude/react-native	@amplitude/analytics-react-native
`enableCoppaControl()`	Refer to the COPPA section for more details.
`disableCoppaControl()`	Refer to the COPPA section for more details.
`setAdvertisingIdForDeviceId()`	No configuration to set ADID as device ID. The SDK still tracks ADID by default because `config.trackingOptions.adid` defaults to `true`. To learn more about how the SDK initializes the device ID, refer to Device ID.
`setAppSetIdForDeviceId()`	No configuration to set App Set ID as device ID. The latest React Native SDK adds App Set ID support in an upcoming release.
`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 always on. To control output, set `config.logLevel` or customize `config.loggerProvider`.
`setLogLevel()`	`config.logLevel`.
`addLogCallback()`	Not fully supported. To customize logging, set `config.loggerProvider`.

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();

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 latest SDK removes setUserProperties(). 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 latest SDK removes clearUserProperties(). 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 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";

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

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

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

logRevenue

The logRevenue() API maps to revenue(). The latest SDK doesn't support receipt or receiptSignature.

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 use setRevenue(6) instead of setPrice(3) and setQuantity(2).

Migration details

Device ID

The maintenance React Native SDK wraps the maintenance iOS, Android, and Browser SDKs and maps React Native calls to native SDK functions, so device ID generation follows the native SDK on each platform. To learn more about device ID lifecycle, refer to the maintenance iOS SDK and maintenance Android SDK docs. You can also call setAdvertisingIdForDeviceId() or setAppSetIdForDeviceId() to set ADID or App Set ID as the device ID.

The latest React Native SDK sets the device ID to the first valid value from this ordered list:

Device ID provided in the configuration on initialization.
The deviceId value from a URL parameter (for example, http://example.com/?deviceId=123456789) when the SDK runs on Web.
Device ID in cookie storage.
A randomly generated 36-character UUID.

Advertising ID

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

COPPA

The maintenance React Native SDK supports COPPA control through enableCoppaControl(). The latest React Native SDK doesn't support that API, but you can still enable COPPA through config.trackingOptions or an Enrichment Plugin that removes identifying information before tracking.

To learn how to enable IDFA, IDFV, ADID, and AppSetId, refer to the Advertising Identifiers documentation.
To turn off IP address tracking, set config.trackingOptions.ipAddress to false.
To remove city or any other identifying information from the payload, use an enrichment Plugin.
The SDK doesn't track location (latitude and longitude).

Session events

The maintenance React Native SDK logs session start and end events automatically when you call trackingSessionEvents(true). In the latest React Native SDK, set config.trackingSessionEvents to true for the same behavior. Events logged within the same session share a session ID, and Amplitude groups events together by session.

Data migration

Starting in v1.3.4, the SDK moves existing maintenance SDK data (events, user ID, and device ID) to the latest SDK by default. To disable the move, set migrateLegacyData to false in the Configuration.

typescript

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

Was this helpful?