Migrate to React Native Unified Plugin
Use this transition guidance to migrate from the Engagement-specific react-native-marketingcloudsdk model to the React Native unified plugin model.
This topic applies only to the customers who use the Engagement-specific React Native implementation.
Note
Overview
The previous React Native integration for Marketing Cloud Engagement uses one package and one static module (MCReactModule) for all features.
The React Native unified plugin integration uses modular packages with async requestSdk() APIs. This model aligns with the native unified SDK architecture and lets you install only the modules you use.
The key changes in the React Native unified implementation are:
- The previous React-Native all-in-one package is split into multiple focused packages (
sfmc-core,push,iam,marketingcloudsdk). - Static method calls are replaced with async module initialization using
requestSdk(). - Identity, attributes, and event-tracking methods are moved to
sfmc-core. - The React Native unified plugins require React Native New Architecture (TurboModules). The bridge support is removed.
Engagement-specific and Unified Package Mapping
Use this table to map your previous dependency to the unified packages. While the previous plugin came as a single package, the unified plugin is split into a core product package and several optional feature packages.
| Engagement-specific React Native dependency | Unified dependency | Required? |
|---|---|---|
react-native-marketingcloudsdk (MobilePush / Engagement) | @sfmc/react-native-marketingcloudsdk | Required. This package replaces the MobilePush or Engagement-specific package. |
| SFMC core bundled inside the Engagement-specific package | @sfmc/react-native-sfmc-core | Auto-installed as a transitive dependency of any product package. |
| Push messaging support bundled inside the Engagement-specific package | @sfmc/react-native-push | Required if your app sends push notifications. |
| In-app messaging support bundled inside the Engagement-specific package | @sfmc/react-native-iam | Required if your app uses in-app messages. |
Prerequisites
The unified plugins require a substantial baseline change from the Engagement-specific plugin. Before you begin your migration, make sure you meet these prerequisites:
- Enable React Native New Architecture app-wide. The unified plugins only run on the new architecture (TurboModules) and doesn’t support the bridge that was supported in Engagement-specific React Native plugin. If your app is still on the previous bridge architecture, enable the new architecture app-wide. For more information, see About the New Architecture.
- Upgrade React Native version to 0.85.1 or later. Upgrade to React Native 0.85.1 or later. Unlike the Engagement-specific React Native plugin, which supported version 0.60 and later, the unified plugins require this higher version.
- Keep your existing Marketing Cloud configuration values available and confirm your App ID, Access Token, Server URL, and MID.
- Perform the migration on a feature branch. Avoid mixing the migration with unrelated work.
- Be prepared to update both JavaScript or TypeScript call sites, and native setup files.
- Make sure your app meets these minimum requirements:
| Components | Minimum Requirement |
|---|---|
| React Native | 0.85.1 or later (with New Architecture enabled) |
| React | 19.0 or later (tested against 19.2.3) |
| Node.js | 20 or later |
| iOS | 15.1 or later (Xcode 16 or later) |
| Android | minSdk 26, compileSdk 36 or later |
| Ruby (CocoaPods) | 3.1.0 or later |
j