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