Below are the required changes to upgrade from an older SDK release to a newer SDK release. These instructions assume Android Studio is the IDE.

5.5.x

The Android SDK now supports only TLS 1.1 and higher; upgrade to SDK version 5.5.x to ensure communication with Marketing Cloud.

From 4.3 and above to 5.0

Full documentation for 5.0.x can be found HERE.

This section shows one-to-one method conversions. Use this information as a reference, not step-by-step instructions. View an example of how to use this reference information in your code.

Global Changes

  • Rebranded all ETPush methods, which stands for ExactTargetPush, to MarketingCloudSdk.
  • Root code package changed from com.exacttarget.etpushsdk to com.salesforce.marketingcloud
  • Artifact group changed from com.exacttarget.etpushsdk to com.salesforce.marketingcloud
  • Artifact ID changed from etsdk to marketingcloudsdk

Configure the SDK

  • Application ID – Instead of ETPushConfig.Builder.setEtAppId(String), use MarketingCloudConfig.Builder.setApplicationId(String)
  • Access Token – Instead of ETPushConfig.Builder.setAccessToken(String), use MarketingCloudConfig.Builder.setAccessToken(String)
  • GCM Sender ID – Instead of ETPushConfig.Builder.setGcmSenderId(String), use MarketingCloudConfig.Builder.setGcmSenderId(String)
  • Analytics – Instead of ETPushConfig.Builder.setAnalyticsEnabled(boolean), use MarketingCloudConfig.Builder.setAnalyticsEnabled(boolean)
  • WAMA (Web and Mobile Analytics) – Instead of ETPushConfig.Builder.setWamaEnabled(boolean), use MarketingCloudConfig.Builder.setPiAnalyticsEnabled(boolean)
  • Geofence Messaging – Instead of ETPushConfig.Builder.setLocationEnabled(boolean), use MarketingCloudConfig.Builder.setGeofencingEnabled(boolean)
  • Proximity Messaging – Instead of ETPushConfig.Builder.setProximityEnabled(boolean), use MarketingCloudConfig.Builder.setProximityEnabled(boolean)
  • Notification Recipient – Instead of ETPushConfig.Builder.setNotificationRecipientClass(Class), use MarketingCloudConfig.Builder.setNotificationRecipient(Class<? extends Activity>)
  • CloudPage Recipient – Instead of ETPushConfig.Builder.setCloudPageRecipientClass(Class), use MarketingCloudConfig.Builder.setCloudPageRecipient(Class<? extends Activity>)
  • OpenDirect Recipient – Instead of ETPushConfig.Builder.setOpenDirectRecipientClass(Class), use MarketingCloudConfig.Builder.setOpenDirectRecipient(Class<? extends Activity>)
  • CloudPages – Instead of ETPushConfig.Builder.setCloudPagesEnabled(boolean), use MarketingCloudConfig.Builder.setCloudPagesEnabled(boolean)
  • Application Label – Instead of ETPushConfig.Builder.setApplicationLabel(String), use MarketingCloudConfig.Builder.setApplicationLabel(String)
  • Notification Resource ID – Instead of ETPushConfig.Builder.setNotificationResourceId(int), use MarketingCloudConfig.Builder.setNotificationSmallIconResId(int)

Other Methods

  • Notification Builder – Instead of ETNotifications.setNotificationBuilder(ETNotificationBuilder), use MarketingCloudConfig.Builder.setNotificationBuilder(NotificationManager.NotificationBuilder)
  • Notification Launch Intent Provider – Instead of ETNotifications.setNotificationLaunchIntent(ETNotificationLaunchIntent), use MarketingCloudConfig.Builder.setNotificationLaunchIntentProvider(NotificationManager.NotificationLaunchIntentProvider)

Methods Removed from Builder

  • Set Log Level – Instead of ETPushConfig.Builder.setLogLevel(int), use MarketingCloudSdk.setLogLevel(int)
  • Set Log Listener – Instead of ETPushConfig.Builder.setLogListener(ETLogListener), use MarketingCloudSdk.setLogListener(MCLogListener)

Logging

The SDK no longer logs unless an MCLogListener is set by your app. Previous versions of the SDK would use Android’s Log if no LogListener was set. To re-enable logging, use MCLogListener.AndroidLogListener, like this: MarketingCloudSdk.setLogListener(new MCLogListener.AndroidLogListener());

Access the SDK

  • Get Instance of SDK – Instead of ETPush.getInstance(), use MarketingCloudSdk.getInstance()

New Method to Access the SDK

Previously, a getInstance method blocked the calling thread if the SDK didn’t complete initialization. Now, you can request an instance of the SDK that doesn’t block the calling thread.

  • MarketingCloudSdk.requestSdk(WhenReadyListener) tries to respond to the listener on the same thread that was used to call requestSdk.MarketingCloudSdk.requestSdk(WhenReadyListener, Looper), which will use the Looper for the callback.

Registration Calls

Edit Registration Information

  • Add Tags – Instead of ETPush.getInstance().addTag(""), use MarketingCloudSdk.getInstance().getRegistrationManager().edit().addTags("","").commit()
  • Add Attributes – Instead of ETPush.getInstance().addAttribute(...), use MarketingCloudSdk.getInstance().getRegistrationManager().edit().setAttribute(...).commit()
  • Set Contact, or Subscriber, Key – Instead of ETPush.getInstance().setSubscriberKey(""), use MarketingCloudSdk.getInstance().getRegistrationManager().edit().setContactKey("").commit()
  • Remove Tags – Instead of ETPush.getInstance().removeTag(""), use MarketingCloudSdk.getInstance().getRegistrationManager().edit().removeTags("").commit()
  • Clear Attributes – Instead of ETPush.getInstance().removeAttribute(""), use MarketingCloudSdk.getInstance().getRegistrationManager().edit().clearAttributes("").commit()

Access Registration Information

  • Tags – Instead of ETPush.getInstance().getTags(), use MarketingCloudSdk.getInstance().getRegistrationManager().getTags()
  • Attributes – Instead of ETPush.getInstance().getAttributes(), use MarketingCloudSdk.getInstance().getRegistrationManager().getAttributes()
  • Contact, or Subscriber, Key – Instead of ETPush.getInstance().getSubscriberKey(), use MarketingCloudSdk.getInstance().getRegistrationManager().getContactKey()
  • System Token – Instead of ETPush.getInstance().getSystemToken(), use MarketingCloudSdk.getInstance().getRegistrationManager().getSystemToken()
  • Device ID – Instead of ETPush.getInstance().getDeviceId(), use MarketingCloudSdk.getInstance().getRegistrationManager().getDeviceId()

Benefits

  • You can make multiple changes to the registration before the SDK tries to send an update if you use an Editor pattern to modify the registration. This pattern makes the SDK perform better because the SDK defers any update actions until after you call commit.
  • Registration.Editor provides a more fluent API to edit registrations via method chaining and allows you to add multiple values in a single method call.

Example

In previous versions, your code may look like this:

In the 208 version of the SDK, it may look like this:

Notifications

  • You used to receive the data from a notification in a Bundle, which is simply a map for which you have to know the exact key to access the data you want. Now, the SDK gives you a NotificationMessage object, which has dedicated methods for the information you need.
  • Instead of providing an Intent when you override a notification’s destination, you now provide a PendingIntent. This change allows your notifications to launch other intents, not just an Activity.
  • To implement, add a line of code: PendingIntent.getActivity(Context, int, Intent(What you would have previously given the SDK), int)

Notification State

You can now disable all notifications from the SDK. Before you would have had to disable each specific type support by the SDK.

  • Enable Notifications – Use MarketingCloudSdk.getInstance().getNotificationManager().enableNotifications()
  • Disable Push (Notifications) – Use MarketingCloudSdk.getInstance().getNotificationManager().disableNotifications()
  • Query Push State (Notifications) – Use MarketingCloudSdk.getInstance().getNotificationManager().areNotificationsEnabled()

Helper Methods

  • Get Default Notification Builder – Instead of ETNotifications.setupNotificationBuilder(Context, Bundle), use NotificationManager.setupNotificationBuilder(Context, NotificationMessage)
  • Create an Open Intent for Analytics – Instead of ETNotifications.createPendingIntentWithOpenAnalyics(Context, Intent, boolean), use NotificationManager.redirectIntentForAnalytics(Context, PendingIntent, NotificationMessage, boolean)
  • Get Default Intent for Notification – Instead of ETNotifications.setupLaunchIntent(Context, Bundle), use NotificationManager.getDefaultLaunchIntentForMessage(Context, NotificationMessage)

    This method only provides an intent for the SDK’s default handler activity. It no longer accounts for any activities set during initialization.

New Methods

  • Cancel Notification – Use NotificationManager.cancelNotificationMessage(Context, NotificationMessage)

You can now cancel an existing notification with only the NotificationMessage.

  • Get Notification Message from Intent – Use NotificationManager.extractMessage(Intent)

When the SDK adds the notification to the intent being launched, it adds the NotificationMessage instead of adding all of the data as extras on the Intent.

Push Messaging: Messaging State

  • Disable Push Messaging – Instead of ETPush.getInstance().disablePush(), use MarketingCloudSdk.getInstance().getPushMessageManager().disablePush()
  • Enable Push Messaging – Instead of ETPush.getInstance().enablePush(), use MarketingCloudSdk.getInstance().getPushMessageManager().enablePush()
  • Query Push Messaging State – Instead of ETPush.getInstance().isPushEnabled(), use MarketingCloudSdk.getInstance().getPushMessageManager().isPushEnabled()

Region, Geofence or Proximity, Messaging: Messaging State

  • Enable Geofence Messaging – Instead of ETLocationManager.getInstance().startWatchingLocation(), use MarketingCloudSdk.getInstance().getRegionMessageManager().enableGeofenceMessaging()
  • Disable Geofence Messaging – Instead of ETLocationManager.getInstance().stopWatchingLocation(), use MarketingCloudSdk.getInstance().getRegionMessageManager().disableGeofenceMessaging()
  • Query Geofence Messaging State – Instead of ETLocationManager.getInstance().isWatchingLocation(), use MarketingCloudSdk.getInstance().getRegionMessageManager().isGeofenceMessagingEnabled()
  • Enable Proximity Messaging – Instead of ETLocationManager.getInstance().startWatchingProximity(), use MarketingCloudSdk.getInstance().getRegionMessageManager().enableProximityMessaging()
  • Disable Proximity Messaging – Instead of ETLocationManager.getInstance().stopWatchingProximity(), use MarketingCloudSdk.getInstance().getRegionMessageManager().disableProximityMessaging()
  • Query Proximity Messaging State – Instead of ETLocationManager.getInstance().isWatchingProximity(), use MarketingCloudSdk.getInstance().getRegionMessageManager().isProximityMessagingEnabled()

CloudPage Messaging

New Methods

  • Get CloudPage Messages – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().getCloudPageMessages()
  • Get Count – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().getMessageCount()
  • Get Unread CountMarketingCloudSdk.getInstance().getCloudPageMessageManager().getUnreadMessageCount()
  • Get Read Count – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().getReadMessageCount()
  • Delete Message – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().deleteMessage(CloudPageMessage)
  • Set Message Read – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().setMessageRead(CloudPageMessage)
  • Set Message Unread – Use MarketingCloudSdk.getInstance().getCloudPageMessageManager().setMessageUnread(CloudPageMessage)

Analytics

  • Track Cart Contents – Instead of ETAnalytics.trackCartContents(PiCart), use MarketingCloudSdk.getInstance().getAnalyticsManager().trackCartContents(PiCart)
  • Track Cart Conversions – Instead of ETAnalytics.trackCartConversions(PiOrder), use MarketingCloudSdk.getInstance().getAnalyticsManager().trackCartConversions(PiOrder)
  • Track Page Views – Instead of ETAnalytics.trackPageViews(...), use MarketingCloudSdk.getInstance().getAnalyticsManager().trackPageViews(...)

SDK Event Callbacks

Previously, the SDK used an EventBus to notify you of events in the SDK. The EventBus required you to create a method whose signature exactly matched an event broadcast through the EventBus, which left room for error. Now, use interfaces designed for each event and register these interfaces with specific methods.

  • Registration Update – Use this register call: MarketingCloudSdk.getInstance().getRegistrationManager().registerForRegistrationEvents(RegistrationEventListener)
  • CloudPage Messages Update – Use this register call: MarketingCloudSdk.getInstance().getCloudPageMessageManager().registerCloudPageResponseListener(CloudPageResponseListener)
  • Geofence Messages Update – Use this register call: MarketingCloudSdk.getInstance().getRegionMessageManager().registerGeofenceMessageResponseListener(GeofenceMessageResponseListener)
  • Proximity Message Update – Use this register call: MarketingCloudSdk.getInstance().getRegionMessageManager().registerProximityMessageResponseListener(ProximityMessageResponseListener)
  • Silent Push Received – Use this register call: MarketingCloudSdk.getInstance().getPushMessageManager().registerSilentPushListener(SilentPushListener)

From v4.2 to v4.3

Full Documentation for v4.2 can be found HERE.

Required Manifest Changes

  • Remove all entries related to receivers and services.
  • Remove any reference to ETLandingPagePresenter.
  • Remove all permissions *except* for ACCESS_FINE_LOCATION and RECEIVE_BOOT_COMPLETED if your application uses Geofences or Beacons.
  • You must leave the android:name field in your <application> tag.

From v4.1 to v4.2

Full Documentation for v4.1.x can be found HERE.

  • Update Google Play Services dependencies to v8.x or higher.

From v4.0 to v4.1

Full Documentation for v4.0.x can be found HERE.

  • Replace receiver’s CONNECTIVITY_CHANGE intent-filter with AIRPLANE_MODE.
  • Remove unnecessary GET_ACCOUNTS permission.