Migration Steps

Use these steps to migrate your app from the Engagement-specific React Native plugin to the React Native unified plugins.

1. Remove the Marketing Cloud Engagement-specific package.

2. Add the unified product package.

3. To use the push or IAM feature packages, add them to your configuration.

4. Reinstall iOS pods.

1. Replace static MCReactModule usage with module initialization through requestSdk().
2. Initialize required modules at app startup and reuse those instances.

requestSdk() caches the initialized SDK instance, so calling it again returns the same module instance.

1. Update method calls based on module ownership and method renames.

2. Find references to previous plugin call sites and update them.

3. Apply essential method renames:

• getSystemToken -> getPushToken
• setMessageRead -> markMessageRead
• deleteMessage -> markMessageDeleted

4. Apply these additional required call-site updates:

• Replace analytics boolean setters with explicit methods:
  • setAnalyticsEnabled(true|false) -> enableAnalytics() / disableAnalytics()
  • setPiAnalyticsEnabled(true|false) -> enablePiAnalytics() / disablePiAnalytics()
• Replace identity APIs:
  • setContactKey / getContactKey -> setProfileId / getProfileId
• Update logging and SDK state handling:
  • enableLogging / disableLogging -> setLogging('DEBUG'|'NONE') (or module-specific logging APIs)
  • logSdkState() -> getSdkState() and log the returned object in your app.

1. Replace event classes from the previous plugin with unified event objects that use objType.

2. Validate event attribute value types. Unified event attributes supports these value types:

• string
• number
• boolean

3. Convert unsupported payload values from the previous plugin before tracking.

If payload from the previous plugin contain nested objects, arrays, or null, convert them to supported value types.

4. Remove unsupported event patterns from the previous plugin:

• IdentityEvent has no direct equivalent in the unified model. Use core identity APIs instead.
• CustomEvent category argument is not supported in unified event objects.

1. Move listener logic to module emitters.

2. Enable registration callback before subscribing.

Call setRegistrationCallback() before subscribing to registration events.

3. Apply platform listener caveats:

• IAM event constants are exported via IamEvent.
• Engagement and push event names are subscribed using string event names.
• Push token refresh listener is Android-only.
• Inbox response listener behavior differs by platform; validate behavior on both Android and iOS.

4. (Optional) Gate whether an in-app message displays.

Use this only if your app needs to allow or suppress in-app messages based on runtime logic.

1. Update both native platforms to the module-based unified configuration model.

• Android: migrate MainApplication.kt setup to module-based config blocks. For more information about Android configuration, see Integrate the Android SDK.
• iOS: migrate AppDelegate.swift setup to module-based config blocks. For more information about iOS configuration, see Integrate the iOS SDK.
• Reapply existing notification, URL-handling, and delegate customization in the new module configuration.

2. Update Android native initialization using module-based configuration.

3. Update iOS native initialization using module-based configuration.

4. Verify mandatory platform configuration requirements.

• React Native New Architecture is enabled.
• Android build minimums match the required versions. For example, minSdk and compileSdk.
• Android 13+ push permission (POST_NOTIFICATIONS) is requested for push flows.
• iOS deployment target and Xcode minimums match the unified plugin requirements.
• Keep all existing notification, URL-handling, and delegate forwarding logic when porting to module-based initialization.

For more information, see Prerequisites.

5. Find native initialization files and verify your final setup.

Migration Checklist.