Migration Steps

Migrate your app from the Marketing Cloud Engagement-specific or Marketing Cloud Next-specific Flutter plugins to the unified Flutter plugin.

  1. Remove the previous plugin package.
  1. Add the unified product package for each product that you use.
  1. To use the push or in-app messaging feature packages, add them to your configuration.
  1. For iOS apps, reinstall your pods.
  1. Replace static SFMCSdk and MobileAppMessaging usage with module initialization through requestSdk().
  2. Initialize required modules at app startup and reuse those instances.
  1. Update method calls based on module ownership and method renames.
Previous Flutter Plugin UsageFlutter Unified Plugin UsageModule
setContactKey, getContactKeysetProfileId, getProfileIdSFMCSdkModule
setAttribute, clearAttribute, getAttributes, trackEventsetAttribute, clearAttribute, getAttributes, track (moved)SFMCSdkModule
getSystemTokengetPushTokenPushModule
addTag, removeTag, getTagssame methods (moved)MarketingCloudSdk
getMessages, setMessageRead, deleteMessagegetAllMessages, markMessageRead, markMessageDeletedMarketingCloudSdk
refreshInbox(callback)refreshInbox() (no callback. Returns Future<bool>)MarketingCloudSdk
analytics, piAnalytics, registrationmodule-specific methodsMarketingCloudSdk
MobileAppMessaging.getDeviceId, isAnalyticsEnabled, enableAnalytics, disableAnalyticssame methods (moved)MobileAppMessaging (sfmc_mobileappmessaging)
MobileAppMessaging.registerForRegistrationEvents(callback)setRegistrationCallback() + registrationEvents streamMobileAppMessaging
  1. Find references to previous plugin call sites and update them.
  1. Rename essential methods:
  • Change getSystemToken to getPushToken.
  • Change getMessages to getAllMessages.
  • Change setMessageRead to markMessageRead.
  • Change deleteMessage to markMessageDeleted.
  1. Apply these additional required call-site updates:
  • Replace analytics boolean setters with explicit methods:
  • Change setAnalyticsEnabled(true|false) to enableAnalytics() / disableAnalytics().
  • Change setPiAnalyticsEnabled(true|false) to enablePiAnalytics() / disablePiAnalytics().
  • Replace identity APIs:
    • Change setContactKey to setProfileId and change getContactKey to getProfileId on SFMCSdkModule.
  • Update logging and SDK state handling:
    • Change SFMCSdk.enableLogging() and disableLogging() to SFMCSdkModule.setLogging(LogLevel.debug|LogLevel.none).
    • Change logSdkState() to SFMCSdkModule.getSdkState() and log the returned value in your app.
  • Update refreshInbox call sites to drop the callback argument. It now returns Future<bool> directly.
  • Adopt new inbox tracking by using MarketingCloudSdk.trackInboxMessageOpened(id). This method doesn’t have an equivalent in the non-unified plugin.
  1. Update CustomEvent calls. The category argument is removed. Use the dedicated event classes instead.
  1. Validate event attribute value types. Unified event attributes support these value types:
  • String
  • num
  • bool

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

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

  2. Remove unsupported event patterns from the previous plugin:

  • EventCategory.identity custom events have no direct equivalent in the unified model. Use setProfileId and setAttribute instead.
  • CartEvent, OrderEvent, and CatalogObjectEvent exist in the unified plugin but are deprecated in favor of CustomEvent. If you keep using them, note that their subtype values use short codes, for example, 'comment', instead of the previous plugin’s descriptive factory names (for example, "Comment Catalog Object").
  1. Move callback-based listeners to Stream subscriptions.

  1. Enable the registration callback before subscribing.

    Call setRegistrationCallback() on MarketingCloudSdk or MobileAppMessaging before subscribing to their respective registrationEvents streams.

  2. Apply platform listener caveats:

  • The inbox response listener, registerInboxResponseListener, uses the previous callback-list pattern instead of a Stream.
  • Location-watching APIs (startWatchingLocation, stopWatchingLocation, isWatchingLocation, and getLastKnownLocation) work only with iOS apps.
  • Proximity messaging APIs (enableProximityMessaging, disableProximityMessaging, and isProximityMessagingEnabled) work only with Android apps.

  1. Determine when to display an in-app message.

    Use this capability 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.
  1. Update Android apps to initialize using module-based configuration.

  1. Update iOS apps to initialize using module-based configuration.

    If you also migrate Marketing Cloud Next, add its builder alongside setEngagement.

  1. Verify mandatory platform configuration requirements.

  • Flutter, Dart SDK, iOS, and Android minimums match the unified plugin requirements.

  • 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 minimum matches the unified plugin requirement.

  • Keep all existing notification, URL-handling, and delegate forwarding logic when porting to module-based initialization.

    For more information, see Prerequisites.

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

Migration Checklist