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.

1flutter pub remove sfmc

2. Add the unified product package for each product that you use.

1flutter pub add sfmc_marketingcloudsdk
2flutter pub add sfmc_mobileappmessaging

3. To use the push or in-app messaging feature packages, add them to your configuration.

1flutter pub add sfmc_push
2flutter pub add sfmc_iam

4. For iOS apps, reinstall your pods.

1cd ios
2pod install

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

1import 'package:sfmc_core/sfmc_core.dart';
2import 'package:sfmc_marketingcloudsdk/sfmc_marketingcloudsdk.dart';
3import 'package:sfmc_push/sfmc_push.dart';
4import 'package:sfmc_iam/sfmc_iam.dart';
5
6await SFMCSdkModule.requestSdk();
7await MarketingCloudSdk.requestSdk();
8await PushModule.requestSdk();
9await IamModule.requestSdk();

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

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

1rg "SFMCSdk\\.|MobileAppMessaging\\."
2rg "setContactKey|getContactKey|getSystemToken|setMessageRead|deleteMessage|logSdkState|registerForRegistrationEvents"

3. Rename essential methods:

• Change getSystemToken to getPushToken.
• Change getMessages to getAllMessages.
• Change setMessageRead to markMessageRead.
• Change deleteMessage to markMessageDeleted.

4. 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// Previous Plugin
2// SFMCSdk.trackEvent(CustomEvent('Purchase', attributes: {'Total': 1234}));
3
4// Unified
5await SFMCSdkModule.track(CustomEvent(name: 'Purchase', attributes: {'Total': 1234}));

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

• String
• num
• bool

3. 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.

4. 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.

1import 'package:sfmc_marketingcloudsdk/sfmc_marketingcloudsdk.dart';
2import 'package:sfmc_mobileappmessaging/sfmc_mobileappmessaging.dart' as mam;
3import 'package:sfmc_push/sfmc_push.dart';
4import 'package:sfmc_iam/sfmc_iam.dart';
5
6// Engagement registration changes:
7final regSub = MarketingCloudSdk.registrationEvents.listen((reg) {
8  print('registration: $reg');
9});
10
11// Marketing Cloud Next registration changes:
12final mamRegSub = mam.MobileAppMessaging.registrationEvents.listen((reg) {
13  print('mam registration: $reg');
14});
15
16// Push token refresh:
17final tokenSub = PushModule.pushTokenStream.listen((token) {
18  print('new token: $token');
19});
20
21// In-App Messaging lifecycle:
22final iamSub = IamModule.inAppMessageEvents.listen((event) {
23  switch (event.type) {
24    case InAppMessageEventType.shouldShow:
25      break;
26    case InAppMessageEventType.didShow:
27      break;
28    case InAppMessageEventType.didClose:
29      break;
30  }
31});
32
33// Always cancel subscriptions when no longer needed:
34regSub.cancel();
35mamRegSub.cancel();
36tokenSub.cancel();
37iamSub.cancel();

2. Enable the registration callback before subscribing.

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

3. 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.

4. 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.

1IamModule.setInAppMessageDecisionHandler((message) {
2  // Return (or resolve) true to display, false to suppress.
3  return message.title != 'Suppress me';
4});
5
6// Clear the handler (restore default "always show"):
7IamModule.setInAppMessageDecisionHandler(null);

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

• For Android apps, migrate your Application class setup to use module-based config blocks.

  For more information, see Configure Flutter for Android and Integrate the Android SDK.

• For iOS apps, migrate your AppDelegate.swift setup to use module-based config blocks.

  For more information, see Configure Flutter for iOS and Integrate the iOS SDK.

• Reapply existing notification, URL-handling, and delegate customization in the new module configuration.

2. Update Android apps to initialize using module-based configuration.

1import com.salesforce.marketingcloud.MarketingCloudConfig
2import com.salesforce.marketingcloud.pushfeature.config.PushFeatureConfig
3import com.salesforce.marketingcloud.inappmessagingfeature.config.InAppMessagingFeatureConfig
4import com.salesforce.marketingcloud.sfmcsdk.SFMCSdk
5import com.salesforce.marketingcloud.sfmcsdk.SFMCSdkModuleConfig
6
7SFMCSdk.configure(this, SFMCSdkModuleConfig.build {
8    engagementModuleConfig = MarketingCloudConfig.builder()
9        .setApplicationId(BuildConfig.MC_APP_ID)
10        .setAccessToken(BuildConfig.MC_ACCESS_TOKEN)
11        .setMarketingCloudServerUrl(BuildConfig.MC_SERVER_URL)
12        .setMid(BuildConfig.MC_MID)
13        .setInboxEnabled(true)
14        .build(this@Application)
15
16    pushFeatureModuleConfig = PushFeatureConfig.builder()
17        .setNotificationCustomizationOptions(/* your notification options */)
18        .setUrlHandler(/* your UrlHandler */)
19        .setShouldShowNotificationListener(/* your ShouldShowNotificationListener */)
20        .build()
21
22    inAppMessagingFeatureModuleConfig = InAppMessagingFeatureConfig.builder()
23        .setUrlHandler(/* your UrlHandler */)
24        .build()
25
26    // If you also migrate Marketing Cloud Next, add its module config
27    // alongside engagementModuleConfig (mamModuleConfig).
28}) { initStatus ->
29    Log.i("SFMC", "SFMC SDK initialization status: $initStatus")
30}

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

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

1import SFMCSDK
2import PushFeatureSDK
3import InAppMessagingFeatureSDK
4import MarketingCloudSDK
5
6var configBuilder = ConfigBuilder()
7
8if let appEndpoint = URL(string: appEndpointURL) {
9    let engagementConfig = MarketingCloudSdkConfigBuilder(appId: appID)
10        .setAccessToken(accessToken)
11        .setMarketingCloudServerUrl(appEndpoint)
12        .setMid(mid)
13        .setInboxEnabled(true)
14        .setLocationEnabled(true)
15        .setAnalyticsEnabled(true)
16        .build()
17    configBuilder = configBuilder.setEngagement(config: engagementConfig)
18}
19
20let pushConfig = PushFeatureConfigBuilder()
21    .setApplicationControlsBadging(true)
22    .build()
23configBuilder = configBuilder.setPushFeature(config: pushConfig)
24
25let iamConfig = InAppMessagingFeatureConfigBuilder().build()
26configBuilder = configBuilder.setInAppMessagingFeature(config: iamConfig)
27
28SFMCSdk.initializeSdk(configBuilder.build()) { status in
29    // Inspect [ModuleInitStatus] per module.
30}

4. 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.

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

1rg "SFMCSdk|MarketingCloudConfig|ConfigBuilder" android ios

Migration Checklist

j

Before You Begin

Use the SDK with Marketing Cloud Next

Use the SDK with Marketing Cloud Engagement

Unified Platform Support

React Native Unified Plugin

Flutter Unified Plugin

Installation

Configure Flutter for Android

Configure Flutter for iOS

API Reference

Migrate to Flutter Unified Plugin

Migration Steps

Migration Checklist