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. ```ts - 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](#coppa) section for more details. | | `disableCoppaControl()` | Refer to the [COPPA](#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](#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()`. ```ts 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()`. ```ts 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. ```ts 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. ```ts 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. ```ts 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 {% callout type="warning" heading="" %} 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. {% /callout %} The `setUserId()` API remains the same. ```ts 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()`. ```ts 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`. ```ts 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](/docs/sdks/analytics/ios/ios-sdk#device-id-lifecycle) and [maintenance Android SDK](/docs/sdks/analytics/android/android-sdk#device-id-lifecycle) 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: 1. Device ID provided in the configuration on initialization. 2. The `deviceId` value from a URL parameter (for example, `http://example.com/?deviceId=123456789`) when the SDK 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 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](/docs/sdks/analytics/react-native/react-native-sdk#enrichment-type-plugin-example) that removes identifying information before tracking. - To learn how to enable IDFA, IDFV, ADID, and AppSetId, refer to the [Advertising Identifiers](/docs/sdks/analytics/react-native/react-native-sdk#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](/docs/sdks/analytics/react-native/react-native-sdk#enrichment-type-plugin-example). - 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](https://github.com/amplitude/Amplitude-TypeScript/releases/tag/%40amplitude%2Fanalytics-react-native%401.3.4), the SDK moves existing [maintenance SDK](/docs/sdks/analytics/react-native/react-native-sdk-maintenance) data (events, user ID, and device ID) to the latest SDK by default. To disable the move, set `migrateLegacyData` to `false` in the [Configuration](/docs/sdks/analytics/react-native/react-native-sdk#configure-the-sdk). ```typescript init(API_KEY, OPTIONAL_USER_ID, { migrateLegacyData: false, }); ```