Migrate to Adobe Experience Platform 3.x SDKs for Android

This Mobile SDK version for Android now supports a minimum API level of 21.

SDK versions

Android BOM

Android extensions

Extension	Version
Mobile Core
Signal
Lifecycle
Identity
Profile
Adobe Experience Platform Assurance
Adobe Experience Platform Edge Network
Identity for Edge Network
Consent for Edge Network
Media for Edge Network
Edge Bridge
Adobe Journey Optimizer
Adobe Journey Optimizer - Decisioning
Places Service
Adobe Analytics
Adobe Analytics - Media Analytics for Audio & Video
Adobe Target
Adobe Campaign Standard
Adobe Campaign Classic
Adobe Audience Manager

Migrate from Adobe Experience Platform 2.x SDKs for Android

If you have implemented Adobe Experience Platform 2.x SDKs for Android, then this guide will help you understand the steps required to migrate your implementation to the Experience Platform 3.x SDKs. In summary, you'll need to:

Update dependencies

When updating to the Experience Platform 3.x SDKs, be sure to review the following updates regarding dependencies.

Gradle

The Adobe SDK BOM artifact enables managing all compatible versions of Adobe Experience Platform Android extensions by specifying a single BOM version. This is now the recommended way to manage Android SDKs. If you are using Gradle to manage your app dependencies, the following example shows how to start using BOM in the build.gradle file.

Using dynamic dependency versions is not recommended for production apps. Refer to this page for managing Gradle dependencies.

dependencies {
    // implementation platform('com.adobe.marketing.mobile:sdk-bom:2.+')
    // implementation 'com.adobe.marketing.mobile:core'
    // implementation 'com.adobe.marketing.mobile:identity'
    // implementation 'com.adobe.marketing.mobile:signal'
    // implementation 'com.adobe.marketing.mobile:lifecycle'
    // implementation 'com.adobe.marketing.mobile:userprofile'

    // Update Adobe SDK BOM artifact to the latest 3.x.x version.
    implementation platform('com.adobe.marketing.mobile:sdk-bom:3.+')
    implementation 'com.adobe.marketing.mobile:core'
    implementation 'com.adobe.marketing.mobile:identity'
    implementation 'com.adobe.marketing.mobile:signal'
    implementation 'com.adobe.marketing.mobile:lifecycle'
    implementation 'com.adobe.marketing.mobile:userprofile'
}
Copied to your clipboard
dependencies {
    // implementation platform('com.adobe.marketing.mobile:sdk-bom:2.+')
    // implementation 'com.adobe.marketing.mobile:core'
    // implementation 'com.adobe.marketing.mobile:identity'
    // implementation 'com.adobe.marketing.mobile:signal'
    // implementation 'com.adobe.marketing.mobile:lifecycle'
    // implementation 'com.adobe.marketing.mobile:userprofile'

    // Update Adobe SDK BOM artifact to the latest 3.x.x version.
    implementation platform('com.adobe.marketing.mobile:sdk-bom:3.+')
    implementation 'com.adobe.marketing.mobile:core'
    implementation 'com.adobe.marketing.mobile:identity'
    implementation 'com.adobe.marketing.mobile:signal'
    implementation 'com.adobe.marketing.mobile:lifecycle'
    implementation 'com.adobe.marketing.mobile:userprofile'
}

Save the build.gradle file and select Sync Project with Gradle Files in Android Studio to download the 3.x SDKs.

Manual library import

If you are importing SDK libraries manually, make sure to update your libraries by downloading the most recent 3.x binaries directly from Maven Central Repository.

Update SDK initialization

The MobileCore.start() API and the registerExtension API for each extension, which were deprecated in the 2.x version of the mobile SDK, have been removed in the 3.x version. If you're still using these APIs, refer here to initialize the SDK and register the extensions using the MobileCore.registerExtensions() API.

Handle API migration and breaking changes

Some of the APIs available in previous major versions of the Mobile SDK for Android are now deprecated or removed. You can choose to replace the obsolete APIs in your code with the alternative APIs in the 3.x version, as described below.

The registerExtension API for each extension that was deprecated in the 2.x version of the mobile SDK has been removed in the 3.x version of the mobile SDK. See the Update SDK initialization section for more details.

MobileCore

Removed API	Alternative API
MobileCore.start(AdobeCallback)	MobileCore.registerExtensions registers extensions and starts event processing by default
MobileCore.dispatchEventWithResponseCallback(Event, AdobeCallbackWithError)	Use MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError) to explicitly specify a timeout
MessagingDelegate	Refer to this page to migrate to PresentationDelegate
InvalidInitException	This exception is no longer thrown by the SDK

Extension Development

Core 3.0.0 is not binary compatible with extensions built using earlier versions. Third-party extension developers are required to recompile their extensions with this version of Core.

Removed API	Alternative API
MobileCore.log(LoggingMode, String, String)	Use logging methods exposed via com.adobe.marketing.mobile.services.Log
MobileCore.registerExtension(Class, ExtensionErrorCallback)	MobileCore.registerExtensions
MobileCore.dispatchEvent(Event, ExtensionErrorCallback)	MobileCore.dispatch(Event) , MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError)
MobileCore.dispatchEvent(Event, AdobeCallback, ExtensionErrorCallback)	MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError)
MobileCore.dispatchResponseEvent(Event, Event, ExtensionErrorCallback)	Use Event.Builder.inResponseToEvent(Event) to create a response event
Event.copy()	Use Event.Builder() to create a new Event
Extension.onUnexpectedError(ExtensionUnexpectedError)	This API is no longer supported by the SDK
ExtensionApi.setSharedEventState(Map, Event, ExtensionErrorCallback)	ExtensionApi.createSharedState(Map, Event), ExtensionApi.createPendingSharedState(Event)
ExtensionApi.setXDMSharedEventState(Map, Event, ExtensionErrorCallback)	ExtensionApi.createXDMSharedState(Map, Event), ExtensionApi.createXDMPendingSharedState(Event)
ExtensionApi.getSharedEventState(String, ExtensionErrorCallback)	ExtensionApi.getSharedState(String, Event, boolean, SharedStateResolution)
ExtensionApi.getXDMSharedEventState(String, Event, ExtensionErrorCallback)	ExtensionApi.getXDMSharedState(String, Event, boolean, SharedStateResolution)
ExtensionApi.clearSharedEventStates(ExtensionErrorCallback)	Use ExtensionApi.createSharedState(Map, Event) with an empty state
ExtensionApi.clearXDMSharedEventStates(ExtensionErrorCallback)	Use ExtensionApi.createXDMSharedState(Map, Event) with an empty state
ExtensionApi.registerEventListener(String, String, Class, ExtensionErrorCallback)	ExtensionApi.registerEventListener(String, String,ExtensionEventListener)
ExtensionApi.registerWildcardEventListener(Class, ExtensionErrorCallback)	ExtensionApi.registerEventListener(String, String, ExtensionEventListener)
LaunchRulesEngine(ExtensionApi)	Use LaunchRulesEngine(String,ExtensionApi) to specify the name of the engine
LaunchRulesEngine.process(Event)	LaunchRulesEngine.evaluateEvent(Event)

ExtensionListener, ExtensionError, ExtensionUnexpectedError, ExtensionErrorCallback classes have been removed as they are no longer referenced after above API changes.

UserProfile

Removed API	Alternative API
UserProfile.updateUserAttribute	UserProfile.updateUserAttributes
UserProfile.removeUserAttribute	UserProfile.removeUserAttributes

Edge Bridge

As of version 3.0.0 of the Adobe Experience Platform Edge Bridge for Android, the table below shows how the trackAction and trackState parameters map to the data node of the Experience Event sent to the Experience Platform Edge Network. Edge Network automatically maps these data variables to Adobe Analytics without additional server-side configuration. If you are using Edge Bridge version 2.x and mapping data to XDM in your datastream, adjustments are required for version 3.0.0.

Data	Key path in v2.x	Key path in v3.+	Description
Action	`data.action`	`data.__adobe.analytics.linkName`	As of v3, set as the custom link name in the Analytics hit. The field `data.__adobe.analytics.linkType` with value `other` is also automatically included.
State	`data.state`	`data.__adobe.analytics.pageName`	As of v3, set as the page name in the Analytics hit.
Context data	`data.contextdata`	`data.__adobe.analytics.contextData`	Context data is a map which includes the custom keys and values specified in the `trackAction` and `trackState` API calls.
Context data prefixed with "&&"	`data.contextdata`	`data.__adobe.analytics`	Before v3, there was no special handling of context data prefixed with "&&". As of v3, context data keys prefixed with "&&" are automatically mapped to Analytics variables and no longer include the "&&" prefix. For example, the key `&&products` is sent as `data.__adobe.analytics.products`. Please note that these keys must be known to Analytics and are case sensitive. Find the full list of supported Analytics variables here.
App identifier	Not included	`data.__adobe.analytics.contextData.a.AppID`	As of v3, the application identifier is automatically added to every tracking event under the key name `a.AppID`.
Customer perspective	Not included	`data.__adobe.analytics.cp`	As of v3, the customer perspective is automatically added to every tracking event. The values are either `foreground` or `background`.

Track action example

Given the track action call:

MobileCore.trackAction("action name", mapOf("key" to "value", "&&products" to ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345"))
Copied to your clipboard
MobileCore.trackAction("action name", mapOf("key" to "value", "&&products" to ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345"))

The resulting Experience Event has the following payload:

{
  "data":{
    "__adobe": {
      "analytics": {
        "linkName": "action name",
        "linkType": "other",
        "cp": "foreground",
        "products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)",
          "key": "value"
        }
      }
    }
  }
}
Copied to your clipboard
{
  "data":{
    "__adobe": {
      "analytics": {
        "linkName": "action name",
        "linkType": "other",
        "cp": "foreground",
        "products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)",
          "key": "value"
        }
      }
    }
  }
}

Track state example

Given the track state call:

MobileCore.trackState("view name", mapOf("&&events" to "event5,event2=2"))
Copied to your clipboard
MobileCore.trackState("view name", mapOf("&&events" to "event5,event2=2"))

The resulting Experience Event has the following payload:

{
  "data":{
    "__adobe": {
      "analytics": {
        "pageName": "view name",
        "cp": "foreground",
        "events": "event5,event2=2",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)"
        }
      }
    }
  }
}
Copied to your clipboard
{
  "data":{
    "__adobe": {
      "analytics": {
        "pageName": "view name",
        "cp": "foreground",
        "events": "event5,event2=2",
        "contextData":{
          "a.AppID": "myApp 1.0 (1)"
        }
      }
    }
  }
}

Edge

Removed API	Alternative API
Formatters.dateToISO8601String	Use TimeUtils.getISO8601UTCDateWithMilliseconds from MobileCore
Formatters.dateToShortDateString	Use TimeUtils.getISO8601FullDate from MobileCore

Adobe Analytics - Media Analytics for Audio & Video

Extension	Mobile Core compatibility	BOM version
com.adobe.marketing.mobile:media:3.0.0	com.adobe.marketing.mobile:core:2.+	com.adobe.marketing.mobile:sdk-bom:2.+
com.adobe.marketing.mobile:media:3.1.0	com.adobe.marketing.mobile:core:3.+	com.adobe.marketing.mobile:sdk-bom:3.+

Please note that the increment to 3.1.0 was preferred for this release in order to synchronize all extensions to same major version. For more details, see this article on aligning major version releases for Adobe Experience Platform Mobile SDKs.

Messaging

Removed API	Alternative API
Message.dismiss(boolean suppressAutoTrack)	Message.dismiss()
Message.evaluateJavascript(String)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use com.adobe.marketing.mobile.services.ui.message.InAppMessageEventHandler.evaluateJavascript(String, AdobeCallback). Refer to this tutorial for more details
Message.handleJavascriptMessage(String, AdobeCallback)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use com.adobe.marketing.mobile.services.ui.message.InAppMessageEventHandler.handleJavascriptMessage(String, AdobeCallback). Refer to this tutorial for more details
Message.getParent()	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use com.adobe.marketing.mobile.messaging.MessagingUtils.getMessageForPresentable(Presentable). Refer to this tutorial for more details
Message.getWebView()	This functionality is no longer supported
MessagingDelegate.shouldShowMessage(FullscreenMessage)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use PresentationDelegate.canShow(Presentable). Refer to this tutorial for more details
MessagingDelegate.onShow(FullscreenMessage)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use PresentationDelegate.onShow(Presentable). Refer to this tutorial for more details
MessagingDelegate.onDismiss(FullscreenMessage)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use PresentationDelegate.onDismiss(Presentable). Refer to this tutorial for more details
MessagingDelegate.urlLoaded(String, FullscreenMessage)	Migrate to com.adobe.marketing.mobile.services.ui.PresentationDelegate and use PresentationDelegate.onContentLoaded(Presentable, PresentationListener.PresentationContent). Refer to this tutorial for more details

Optimize

Removed API	Alternative API
com.adobe.marketing.mobile.optimize.Proposition	com.adobe.marketing.mobile.optimize.OptimizeProposition

Adobe Campaign Classic

Removed API	Alternative API
AEPMessagingService.handleRemoteMessage(Context, RemoteMessage)	Coming soon

Frequently asked questions

Why do I see 'unresolved reference' errors related to `MessagingDelegate` when upgrading to 3.x SDK?

The Mobile Core 3.x SDK for Android includes changes to SDK presentation management that break compatiblity with earlier versions of the SDK. com.adobe.marketing.mobile.services.MessagingDelegate and its usage has been removed in favor of com.adobe.marketing.mobile.services.ui.PresentationDelegate. If your application uses MessagingDelegate for granular control of in-app messages, refer to this page for more details on using PresentationDelegate.

Why do I see 'java.lang.NoSuchMethodError' after upgrading to the 3.x version of Mobile SDK for Android?

The Mobile Core 3.x SDK for Android includes changes that break compatiblity with solution SDKs developed for earlier verisons of the Mobile Core SDK.

If you attempt to use 3.x Mobile Core SDK with solution SDKs that were built for previous versions of Mobile Core in your app, you may encounter the following errors:

2024-04-03 17:45:02.501 XXXXX-XXXX/XXXX E/AndroidRuntime: FATAL EXCEPTION: main
    Process: XXX, PID: XXXXXX
    java.lang.NoSuchMethodError: No static method getCore()Lcom/adobe/marketing/mobile/Core; in class Lcom/adobe/marketing/mobile/MobileCore; or its super classes (declaration of 'com.adobe.marketing.mobile.MobileCore' appears in XXX

2024-04-03 17:45:02.501 XXXXX-XXXX/XXXX E/AndroidRuntime: FATAL EXCEPTION: main
    Process: XXX, PID: XXXXX
    java.lang.NoClassDefFoundError: Failed resolution of: Lcom/adobe/marketing/mobile/ExtensionErrorCallback;
Copied to your clipboard
2024-04-03 17:45:02.501 XXXXX-XXXX/XXXX E/AndroidRuntime: FATAL EXCEPTION: main
    Process: XXX, PID: XXXXXX
    java.lang.NoSuchMethodError: No static method getCore()Lcom/adobe/marketing/mobile/Core; in class Lcom/adobe/marketing/mobile/MobileCore; or its super classes (declaration of 'com.adobe.marketing.mobile.MobileCore' appears in XXX

2024-04-03 17:45:02.501 XXXXX-XXXX/XXXX E/AndroidRuntime: FATAL EXCEPTION: main
    Process: XXX, PID: XXXXX
    java.lang.NoClassDefFoundError: Failed resolution of: Lcom/adobe/marketing/mobile/ExtensionErrorCallback;

To resolve these errors, upgrade all your solution SDKs to the most recent versions using Adobe SDK BOM.

Upgrade the extensions within the mobile property in the Data Collection UI to see latest installation instructions for the mobile platform extensions.

Android

Migrate to 2.x SDKs