Migrate to Adobe Experience Platform 3.x SDKs for Android

data-variant=info

data-slots=text
This Mobile SDK version for Android now supports a minimum API level of 21.

SDK versions

Android BOM

descriptive text

Android extensions

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

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:

  1. Update dependencies
  2. Update SDK initialization
  3. Handle API migration and breaking changes

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.

data-variant=warning

data-slots=text
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'
}

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.

data-variant=warning

data-slots=text
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 "&&". <br/> <br/> 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"))

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"
        }
      }
    }
  }
}
Track state example

Given the track state call:

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)"
        }
      }
    }
  }
}

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.mobile3.0.0
com.adobe.marketing.mobile2.+
com.adobe.marketing.mobile2.+
com.adobe.marketing.mobile3.1.0
com.adobe.marketing.mobile3.+
com.adobe.marketing.mobile3.+

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

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;

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.