diff --git a/gatsby-config.js b/gatsby-config.js index e07338f9f9..acbc9c95be 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -216,7 +216,7 @@ module.exports = { path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate", pages: [ { - title: "Progrmmatically control the display of in-app messages", + title: "Programmatically control the display of in-app messages", path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate" }, { @@ -829,6 +829,9 @@ module.exports = { title: "Android", path: "/resources/migration/android", pages: [{ + title: "Migrate to 3.x SDKs", + path: "/resources/migration/android/migrate-to-3x" + },{ title: "Migrate to 2.x SDKs", path: "/resources/migration/android/migrate-to-2x" } diff --git a/src/pages/edge/adobe-journey-optimizer-decisioning/api-reference.md b/src/pages/edge/adobe-journey-optimizer-decisioning/api-reference.md index 75672aaa11..653c35a9b3 100644 --- a/src/pages/edge/adobe-journey-optimizer-decisioning/api-reference.md +++ b/src/pages/edge/adobe-journey-optimizer-decisioning/api-reference.md @@ -122,10 +122,14 @@ iOS -### Proposition/OptimizeProposition +### OptimizeProposition This class represents the decision propositions received from the decisioning services, upon a personalization query request to the Experience Edge network. + + +In SDK versions lower than Android 3.0.0 and iOS 5.0.0, this class was named `Proposition` + Android diff --git a/src/pages/edge/adobe-journey-optimizer-decisioning/tabs/api-reference.md b/src/pages/edge/adobe-journey-optimizer-decisioning/tabs/api-reference.md index 3328b38262..5440d062ed 100644 --- a/src/pages/edge/adobe-journey-optimizer-decisioning/tabs/api-reference.md +++ b/src/pages/edge/adobe-journey-optimizer-decisioning/tabs/api-reference.md @@ -101,11 +101,11 @@ NSString *extensionVersion = [AEPMobileOptimize extensionVersion]; #### Syntax ```java -public static void getPropositions(final List decisionScopes, final AdobeCallback> callback) +public static void getPropositions(final List decisionScopes, final AdobeCallback> callback) ``` * _decisionScopes_ is a list of decision scopes for which propositions are requested. -* _callback_ `call` method is invoked with propositions map of type `Map`. If the callback is an instance of [AdobeCallbackWithError](../../home/base/mobile-core/api-reference.md#adobecallbackwitherror), and if the operation times out or an error occurs in retrieving propositions, the `fail` method is invoked with the appropriate [AdobeError](../../home/base/mobile-core/api-reference.md#adobeerror). +* _callback_ `call` method is invoked with propositions map of type `Map`. If the callback is an instance of [AdobeCallbackWithError](../../home/base/mobile-core/api-reference.md#adobecallbackwitherror), and if the operation times out or an error occurs in retrieving propositions, the `fail` method is invoked with the appropriate [AdobeError](../../home/base/mobile-core/api-reference.md#adobeerror). #### Example @@ -117,22 +117,22 @@ final List decisionScopes = new ArrayList<>(); decisionScopes.add(decisionScope1); decisionScopes.add(decisionScope2); -Optimize.getPropositions(scopes, new AdobeCallbackWithError>() { +Optimize.getPropositions(scopes, new AdobeCallbackWithError>() { @Override public void fail(final AdobeError adobeError) { // handle error } @Override - public void call(Map propositionsMap) { + public void call(Map propositionsMap) { if (propositionsMap != null && !propositionsMap.isEmpty()) { // get the propositions for the given decision scopes if (propositionsMap.contains(decisionScope1)) { - final Proposition proposition1 = propsMap.get(decisionScope1) + final OptimizeProposition proposition1 = propsMap.get(decisionScope1) // read proposition1 offers } if (propositionsMap.contains(decisionScope2)) { - final Proposition proposition2 = propsMap.get(decisionScope2) + final OptimizeProposition proposition2 = propsMap.get(decisionScope2) // read proposition2 offers } } @@ -225,22 +225,22 @@ AEPDecisionScope* decisionScope2 = [[AEPDecisionScope alloc] initWithName: @"myS #### Syntax ```java -public static void onPropositionsUpdate(final AdobeCallback> callback) +public static void onPropositionsUpdate(final AdobeCallback> callback) ``` -* _callback_ `call` method is invoked with propositions map of type `Map`. If the callback is an instance of `AdobeCallbackWithError`, and if the operation times out or an error occurs in retrieving propositions, the `fail` method is invoked with the appropriate `AdobeError`. +* _callback_ `call` method is invoked with propositions map of type `Map`. If the callback is an instance of `AdobeCallbackWithError`, and if the operation times out or an error occurs in retrieving propositions, the `fail` method is invoked with the appropriate `AdobeError`. #### Example ```java -Optimize.onPropositionsUpdate(new AdobeCallbackWithError>() { +Optimize.onPropositionsUpdate(new AdobeCallbackWithError>() { @Override public void fail(final AdobeError adobeError) { // handle error } @Override - public void call(final Map propositionsMap) { + public void call(final Map propositionsMap) { if (propositionsMap != null && !propositionsMap.isEmpty()) { // handle propositions } @@ -482,52 +482,52 @@ public class DecisionScope: NSObject, Codable { #### Java ```java -public class Proposition { +public class OptimizeProposition { /** - * Constructor creates a {@code Proposition} using the provided propostion {@code id}, {@code offers}, {@code scope} and {@code scopeDetails}. + * Constructor creates a {@code OptimizeProposition} using the provided propostion {@code id}, {@code offers}, {@code scope} and {@code scopeDetails}. * * @param id {@link String} containing proposition identifier. * @param offers {@code List} containing proposition items. * @param scope {@code String} containing encoded scope. * @param scopeDetails {@code Map} containing scope details. */ - Proposition(final String id, final List offers, final String scope, final Map scopeDetails) {...} + OptimizeProposition(final String id, final List offers, final String scope, final Map scopeDetails) {...} /** - * Gets the {@code Proposition} identifier. + * Gets the {@code OptimizeProposition} identifier. * - * @return {@link String} containing the {@link Proposition} identifier. + * @return {@link String} containing the {@link OptimizeProposition} identifier. */ public String getId() {...} /** - * Gets the {@code Proposition} items. + * Gets the {@code OptimizeProposition} items. * - * @return {@code List} containing the {@link Proposition} items. + * @return {@code List} containing the {@link OptimizeProposition} items. */ public List getOffers() {...} /** - * Gets the {@code Proposition} scope. + * Gets the {@code OptimizeProposition} scope. * - * @return {@link String} containing the encoded {@link Proposition} scope. + * @return {@link String} containing the encoded {@link OptimizeProposition} scope. */ public String getScope() {...} /** - * Gets the {@code Proposition} scope details. + * Gets the {@code OptimizeProposition} scope details. * - * @return {@code Map} containing the {@link Proposition} scope details. + * @return {@code Map} containing the {@link OptimizeProposition} scope details. */ public Map getScopeDetails() {...} /** - * Generates a map containing XDM formatted data for {@code Experience Event - Proposition Reference} field group from this {@code Proposition}. + * Generates a map containing XDM formatted data for {@code Experience Event - OptimizeProposition Reference} field group from this {@code OptimizeProposition}. * * The returned XDM data does not contain {@code eventType} for the Experience Event. * - * @return {@code Map} containing the XDM data for the proposition reference. + * @return {@code Map} containing the XDM data for the OptimizeProposition reference. */ public Map generateReferenceXdm() {...} } @@ -722,26 +722,26 @@ public class Offer { public Map getCharacteristics() {...} /** - * Gets the containing {@code Proposition} for this {@code Offer}. + * Gets the containing {@code OptimizeProposition} for this {@code Offer}. * - * @return {@link Proposition} instance. + * @return {@link OptimizeProposition} instance. */ - public Proposition getProposition() {...} + public OptimizeProposition getProposition() {...} /** * Dispatches an event for the Edge network extension to send an Experience Event to the Edge network with the display interaction data for the - * given {@code Proposition} offer. + * given {@code OptimizeProposition} offer. */ public void displayed() {...} /** * Dispatches an event for the Edge network extension to send an Experience Event to the Edge network with the tap interaction data for the - * given {@code Proposition} offer. + * given {@code OptimizeProposition} offer. */ public void tapped() {...} /** - * Generates a map containing XDM formatted data for {@code Experience Event - Proposition Interactions} field group from this {@code Proposition} item. + * Generates a map containing XDM formatted data for {@code Experience Event - Proposition Interactions} field group from this {@code OptimizeProposition} item. * * The returned XDM data does contain the {@code eventType} for the Experience Event with value {@code decisioning.propositionDisplay}. * @@ -753,7 +753,7 @@ public class Offer { public Map generateDisplayInteractionXdm() {...} /** - * Generates a map containing XDM formatted data for {@code Experience Event - Proposition Interactions} field group from this {@code Proposition} offer. + * Generates a map containing XDM formatted data for {@code Experience Event - Proposition Interactions} field group from this {@code OptimizeProposition} offer. * * The returned XDM data contains the {@code eventType} for the Experience Event with value {@code decisioning.propositionInteract}. * diff --git a/src/pages/edge/adobe-journey-optimizer/code-based/tabs/api-reference.md b/src/pages/edge/adobe-journey-optimizer/code-based/tabs/api-reference.md index 0f9fd8b36a..05a0dcb4d5 100644 --- a/src/pages/edge/adobe-journey-optimizer/code-based/tabs/api-reference.md +++ b/src/pages/edge/adobe-journey-optimizer/code-based/tabs/api-reference.md @@ -2,11 +2,6 @@ noIndex: true --- - - -### Coming soon - - @@ -128,11 +122,6 @@ AEPSurface* surface2 = [[AEPSurface alloc] initWithPath: @"myView#button"]; }]; ``` - - -### Coming soon - - diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native.md index 0ee50d5991..6cda431818 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native.md @@ -7,6 +7,7 @@ keywords: - JavaScript event - Messaging - Messaging delegate +- PresentationDelegate - Tutorial --- @@ -16,25 +17,29 @@ import Tabs from './tabs/javascript-from-native.md' You can execute JavaScript in an in-app message from native code by completing the following steps: -* [Implement and assign a `MessagingDelegate`](#implement-and-assign-a-messagingdelegate) -* [Obtain a reference to the web view](#obtain-a-reference-to-the-web-view) +* [Implement and assign a `PresentationDelegate`/ `MessagingDelegate`](#implement-and-assign-a-presentationdelegate-messagingdelegate) +* [Obtain a reference to the web view](#obtain-a-reference-to-the-inappmessageeventhandler-web-view) * [Call the JavaScript method](#call-the-javascript-method) -## Implement and assign a `MessagingDelegate` +## Implement and assign a `PresentationDelegate`/ `MessagingDelegate` -To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `MessagingDelegate`. +To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `PresentationDelegate` or `MessagingDelegate` (for older Android SDK versions and iOS SDK) you are using. -For more detailed instructions on implementing and using a MessagingDelegate, please read the [tutorial on using MessagingDelegate](./messaging-delegate.md). +Please read the [tutorial](./messaging-delegate.md) for more detailed instructions on implementing and using a PresentationDelegate/ MessagingDelegate (for older Android SDK versions and iOS SDK). -## Obtain a reference to the web view +## Obtain a reference to the `InAppMessageEventHandler`/ web view In the `shouldShowMessage` function of the `MessagingDelegate`, get a reference to the web view used by the message. - + -Android +Android 3.x - + + +Android 2.x (Older version) + + iOS @@ -42,11 +47,15 @@ iOS ## Call the JavaScript method - + + +Android 3.x + + -Android +Android 2.x (Older version) - + iOS @@ -58,4 +67,4 @@ The test apps in this repository demonstrate executing JavaScript code from an i * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate.md index 285d367111..1afb640ff8 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate.md @@ -13,15 +13,19 @@ import Tabs from './tabs/messaging-delegate.md' # Programmatically control the display of in-app messages -You can now implement a `MessagingDelegate` in order to be alerted when specific events occur during the lifecycle of an in-app message. +You can now implement a `PresentationDelegate` or `MessagingDelegate`(for older Android SDK versions and iOS SDK) in order to be alerted when specific events occur during the lifecycle of an in-app message. ## Register the delegate - + -Android +Android 3.x - + + +Android 2.x (Older version) + + iOS @@ -29,11 +33,15 @@ iOS ## MessagingDelegate definition - + + +Android 3.x + + -Android +Android 2.x (Older version) - + iOS @@ -41,11 +49,15 @@ iOS ## Retrieve the `Message` object - + -Android +Android 3.x - + + +Android 2.x (Older version) + + iOS @@ -53,27 +65,19 @@ iOS ## Controlling when a message should be shown to the end user - + -Android +Android 3.x - + -iOS +Android 2.x (Older version) - - -### Integrating the message into an existing UI - - - -Android - - + iOS - + ## Examples @@ -81,7 +85,7 @@ The test apps in this repository demonstrate using a `MessagingDelegate`: * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) #### Further reading diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript.md index fceb087ef9..8d2e358448 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript.md @@ -7,6 +7,7 @@ keywords: - JavaScript event - Messaging - Messaging delegate +- PresentationDelegate - Tutorial --- @@ -16,23 +17,27 @@ import Tabs from './tabs/native-from-javascript.md' You can handle events from in-app message interactions natively within your application by completing the following steps: -* [Implement and assign a `MessagingDelegate`](#implement-and-assign-a-messagingdelegate) +* [Implement and assign a `PresentationDelegate`/`MessagingDelegate`](#implement-and-assign-a-presentationdelegate-messagingdelegate) * [Register a JavaScript handler for your In-App Message](#register-a-javascript-handler-for-your-in-app-message) * [Post the JavaScript message from your In-App Message](#post-the-javascript-message-from-your-in-app-message) -## Implement and assign a `MessagingDelegate` +## Implement and assign a `PresentationDelegate`/ `MessagingDelegate` -To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `MessagingDelegate`. +To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `PresentationDelegate` or `MessagingDelegate` (for older Android SDK versions and iOS SDK). -For more detailed instructions on implementing and using a MessagingDelegate, please read the [tutorial on using MessagingDelegate](./messaging-delegate.md). +Please read the [tutorial](./messaging-delegate.md) for more detailed instructions on implementing and using a PresentationDelegate/ MessagingDelegate (for older Android SDK versions and iOS SDK). ## Register a JavaScript handler for your In-App Message - + -Android +Android 3.x - + + +Android 2.x (Older version) + + iOS @@ -80,4 +85,4 @@ The test apps in this repository demonstrate calling native code from JavaScript * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/javascript-from-native.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/javascript-from-native.md index 961593e431..fc6c432c0c 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/javascript-from-native.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/javascript-from-native.md @@ -1,4 +1,40 @@ - + + +In the `onShow` function of the `PresentationDelegate`, obtain a reference to the `InAppMessageEventHandler` for use in Javascript interactions. + +#### Kotlin + +```kotlin +var eventHandler: InAppMessageEventHandler? = null +var currentMessagePresentable: Presentable? = null + +override fun onShow(presentable: Presentable<*>) { + if (presentable.getPresentation() !is InAppMessage) { + return + } + currentMessagePresentable = presentable as Presentable + eventHandler = currentMessagePresentable?.getPresentation()?.eventHandler + +} +``` + +#### Java + +```java +InAppMessageEventHandler eventHandler = null; +Presentable currentMessagePresentable = null; + +@Override +public void onShow(Presentable presentable) { + if (!(presentable.getPresentation() instanceof InAppMessage)) { + return; + } + currentMessagePresentable = (Presentable) presentable; + eventHandler = currentMessagePresentable.getPresentation().getEventHandler(); +} +``` + + On Android, the web view is represented as `WebView`. @@ -34,7 +70,52 @@ func shouldShowMessage(message: Showable) -> Bool { } ``` - + + +With a reference to the `InAppMessageEventHandler`, the instance method `evaluateJavascript(String, AdobeCallback)` can now be leveraged to call a JavaScript method. + +Further details of this API are explained in the [Android](https://developer.android.com/reference/android/webkit/WebView#evaluateJavascript(java.lang.String,%20android.webkit.ValueCallback%3Cjava.lang.String%3E)) documentation - the example below is provided for the purpose of demonstration: + +#### Kotlin + +```kotlin +var eventHandler: InAppMessageEventHandler? = null +var currentMessagePresentable: Presentable? = null + +override fun onShow(presentable: Presentable<*>) { + if (presentable.getPresentation() !is InAppMessage) { + return + } + currentMessagePresentable = presentable as Presentable + eventHandler = currentMessagePresentable?.getPresentation()?.eventHandler + eventHandler?.evaluateJavascript("startTimer()") { content -> + // do something with the content + } +} +``` + +#### Java + +```java +InAppMessageEventHandler eventHandler = null; +Presentable currentMessagePresentable = null; + +@Override +public void onShow(Presentable presentable) { + if (!(presentable.getPresentation() instanceof InAppMessage)) { + return; + } + currentMessagePresentable = (Presentable) presentable; + eventHandler = currentMessagePresentable.getPresentation().getEventHandler(); + if (eventHandler != null) { + eventHandler.evaluateJavascript("startTimer()", s -> { + // do something with the content + }); + } +} +``` + + With a reference to the `WebView`, the instance method `public void evaluateJavascript(@NonNull String script, @Nullable ValueCallback resultCallback)` can now be leveraged to call a JavaScript method. diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/messaging-delegate.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/messaging-delegate.md index bb5a1d0a55..595e593aa9 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/messaging-delegate.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/messaging-delegate.md @@ -1,6 +1,35 @@ - + -On Android, the delegate is registered with the Adobe Service Provider. The `ServiceProvider` class maintains an optional property that holds reference to the `FullscreenMessaageDelegate`. +On Android 3.x, you must implement the `PresentationDelegate` interface to be alerted of in-app message events. The `AEPUIService` class, which implements the `UIService` interface, maintains an optional property that holds reference to the `PresentationDelegate`. + +#### Kotlin + +```kotlin +// accessed via the public class ServiceProvider which contains a getter for the UIService implementation +interface UIService { + fun setPresentationDelegate(presentationDelegate: PresentationDelegate) +} +``` + +On Android 3.x, the custom implementation of `PresentationDelegate` is registered with the `UIService` by accessing it using the `ServiceProvider`. + +#### Kotlin + +```kotlin +val myPresentationDelegate = CustomDelegate() +ServiceProvider.getInstance().uiService.setPresentationDelegate(myPresentationDelegate) +``` + +#### Java + +```java +CustomDelegate myPresentationDelegate = new CustomDelegate(); +ServiceProvider.getInstance().getUIService().setPresentationDelegate(myPresentationDelegate); +``` + + + +On Android 2.x and older, the delegate is registered with the Adobe Service Provider. The `ServiceProvider` class maintains an optional property that holds reference to the `FullscreenMessaageDelegate`. #### Java @@ -36,7 +65,88 @@ let myMessagingDelegate = InAppMessagingHandler() MobileCore.messagingDelegate = myMessagingDelegate ``` - + + +The `PresentationDelegate` interface extends the `PresentationListener` and `PresentationLever` interfaces. It is available in the `com.adobe.marketing.mobile.services.ui` package. + +#### PresentationDelegate interface + +**Kotlin** + +```kotlin +/** + * A delegate that can be used to observe and control the lifecycle of [Presentation]'s managed by the SDK. + */ +interface PresentationDelegate : PresentationListener, PresentationLever +``` + +#### PresentationListener interface + +**Kotlin** + +```kotlin +/** + * A listener for observing the lifecycle of presentations managed by the SDK. + */ +interface PresentationListener { + /** + * Invoked when a the presentable is shown. + * @param presentable the [Presentable] that was shown + */ + fun onShow(presentable: Presentable<*>) + + /** + * Invoked when a presentable is hidden. + * @param presentable the [Presentable] that was hidden + */ + fun onHide(presentable: Presentable<*>) + + /** + * Invoked when a presentable is dismissed. + * @param presentable the [Presentable] that was dismissed + */ + fun onDismiss(presentable: Presentable<*>) + + /** + * Invoked when the content in the presentable is loaded. + * @param presentable the [Presentable] into which that was loaded + * @param presentationContent optional [PresentationContent] that was loaded into the presentable + */ + fun onContentLoaded(presentable: Presentable<*>, presentationContent: PresentationContent?) + + /** + * Defines the types of content that can be loaded into a [Presentable]. + */ + sealed class PresentationContent { + /** + * Content loaded from a URL. + * @param url the URL from which the content was loaded + */ + class UrlContent(val url: String) : PresentationContent() + } +} +``` + +#### PresentationLever interface + +**Kotlin** + +```kotlin +/** + * A gating mechanism for implementers to restrict the display of a [Presentable] based on specific + * set of conditions. + */ +interface PresentationLever { + /** + * Returns true if [presentable] can be shown, false otherwise. + * @param presentable the [Presentable] to check if it can be shown + * @return true if [presentable] can be shown, false otherwise + */ + fun canShow(presentable: Presentable<*>): Boolean +} +``` + + The `MessagingDelegate` interface, which is implemented in the `AEPServices` framework, is defined below: @@ -133,7 +243,38 @@ public protocol MessagingDelegate { } ``` - + + +The `Message` class has the business logic related to the in-app message to perform actions like sending tracking events on interactions and suppress tracking. The class that implements `PresentationDelegate` will receive a `Presentable` object, which is the Mobile Core class containing in-app message view. You will need to get the `Message` object associated with `Presentable` object using the `MessagingUtils.getMessageForPresentable(Presentable)` . + +#### Kotlin + +```kotlin +var currentMessagePresentable: Presentable? = null +override fun onShow(presentable: Presentable<*>) { + if (presentable.getPresentation() !is InAppMessage) { + return + } + currentMessagePresentable = presentable as Presentable + val message = MessagingUtils.getMessageForPresentable(currentMessagePresentable) + } + ``` + +#### Java + + ```java +Presentable currentMessagePresentable = null; +@Override +public void onShow(Presentable presentable) { + if (!(presentable.getPresentation() instanceof InAppMessage)) { + return; + } + currentMessagePresentable = (Presentable) presentable; + Message message = MessagingUtils.getMessageForPresentable(currentMessagePresentable); +} + ``` + + The user interface methods (except for `onShowFailure()`) in a `MessagingDelegate` implementation will be passed an `AEPMessage` object. An `AEPMessage` object is the Android Core implementation of the `FullscreenMessage` interface. It contains a reference to the parent `Message` class and is your primary way to interact with the message. @@ -170,7 +311,93 @@ func onShow(message: Showable) { } ``` - + + +If a custom `PresentationDelegate` implementation has been set in the `UIService`, the delegate's `canShow` method will be called prior to displaying an in-app message for which the end user has qualified. You are responsible for returning `true` if the message should be shown, or `false` if the message should be suppressed. If you returned `false` in the `canShow` method, you can store a reference to the Message object, and call the show() method on it at a later time. + +An example of when you may choose to suppress an in-app message due to the status of some other workflow within the app and show it at a later time upon completion of the other workflow can be seen below: + +#### Kotlin + +```kotlin +var currentMessage: Message? = null +var anotherWorkflowStatus: String = "inProgress" + +// Invoked prior to displaying Presentable to check if it can be shown +// if true is returned, the Presentable will be shown immediately +// if false is returned, the message will not be shown +override fun canShow(presentable: Presentable<*>): Boolean { + // canShow is called for all Presentable types: Alert, FloatingButton, InAppMessage + // check the type of Presentable before deciding the return value + if (presentable.getPresentation() !is InAppMessage) + return true + + if(anotherWorkflowStatus.equals("inProgress")) { + val currentMessagePresentable = presentable as Presentable + + // optional : hold this reference for later use + // access the Message for Presentable + currentMessage = MessagingUtils.getMessageForPresentable(currentMessagePresentable) + + println("message was suppressed: ${currentMessage?.id}") + currentMessage?.track("message suppressed", MessagingEdgeEventType.TRIGGER) + + return false + } + + return true +} + + +fun otherWorkflowFinished() { + anotherWorkflowStatus = "complete" + currentMessage?.show() +} +``` + +#### Java + +```java +Message currentMessage = null; +String anotherWorkflowStatus = "inProgress"; + +// Invoked prior to displaying Presentable to check if it can be shown +// if true is returned, the Presentable will be shown immediately +// if false is returned, the message will not be shown +@Override +public boolean canShow(Presentable presentable) { + // canShow is called for all Presentable types: Alert, FloatingButton, InAppMessage + // check the type of Presentable before deciding the return value + if (!(presentable.getPresentation() instanceof InAppMessage)) { + return true; + } + + if(anotherWorkflowStatus.equals("inProgress")) { + Presentable currentMessagePresentable = (Presentable) presentable; + + // optional : hold this reference for later use + // access the Message for Presentable + currentMessage = MessagingUtils.getMessageForPresentable(currentMessagePresentable); + if (currentMessage != null) { + System.out.println("message was suppressed: " + currentMessage.getId()); + message.track("message suppressed", MessagingEdgeEventType.TRIGGER); + } + + return false; + } + + return true; +} + +public void otherWorkflowFinished() { + anotherWorkflowStatus = "complete"; + if (currentMessage != null) { + currentMessage.show(); + } +} +``` + + If a custom `MessagingDelegate` has been set in the `ServiceProvider`, this delegate's `shouldShowMessage` method will be called prior to displaying an in-app message for which the end user has qualified. You are responsible for returning `true` if the message should be shown, or `false` if the message should be suppressed. @@ -256,58 +483,3 @@ func shouldShowMessage(message: Showable) -> Bool { return true } ``` - - - -If you would like to manually integrate the `View` that contains the UI for an in-app message, you can do so by accessing the `WebView` directly in a `MessagingDelegate` method. - -In the example below, you can decide whether or not the in-app message should be directly integrated into your existing UI. If so, you capture a reference to the message's `WebView` and return `false` to prevent the message from being shown by the SDK: - -#### Java - -```java -private Message currentMessage = null; -private boolean shouldIntegrateMessageDirectly = true; -private MessageWebView inAppMessageView; - -@Override -public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { - if (shouldIntegrateMessageDirectly) { - this.currentMessage = (Message) fullscreenMessage.getParent(); - - // cast to MessageWebView to access the startInAppMessage function - inAppMessageView = (MessageWebView) currentMessage.getWebView(); - - return false; - } - - return true; -} -``` - - - -If you would like to manually integrate the `View` that contains the UI for an in-app message, you can do so by accessing the `WKWebView` directly in a `MessagingDelegate` method. - -IMPORTANT! - The `shouldShowMessage` delegate method is called on a background thread. Any direct interactions with the Message's `WKWebView` made by the delegate should be dispatched back to the main thread. - -In the example below, you can decide whether or not the in-app message should be directly integrated into your existing UI. If so, you capture a reference to the message's `WKWebView` and return `false` to prevent the message from being shown by the SDK: - -#### Swift - -```swift -var inAppMessageView: WKWebView? - -func shouldShowMessage(message: Showable) -> Bool { - if shouldIntegrateMessageDirectly { - let fullscreenMessage = message as? FullscreenMessage - let message = fullscreenMessage?.parent - - inAppMessageView = message?.view as? WKWebView - - return false - } - - return true -} -``` diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/native-from-javascript.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/native-from-javascript.md index 0e1f2f5b9d..3021afc050 100644 --- a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/native-from-javascript.md +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/native-from-javascript.md @@ -1,4 +1,61 @@ - + + +In the `onShow` function of the `PresentationDelegate`, call `handleJavascriptMessage(String, AdobeCallback)` to register your handler. + +The name of the message you intend to pass from the JavaScript side should be specified in the first parameter. + +The following example shows a handler that dispatches an `decisioning.propositionInteract` Experience Event natively when the JavaScript of the in-app message posts a myInappCallback message: + +#### Kotlin + +```kotlin +var eventHandler: InAppMessageEventHandler? = null +var currentMessagePresentable: Presentable? = null + +override fun onShow(presentable: Presentable<*>) { + if (presentable.getPresentation() !is InAppMessage) { + return + } + currentMessagePresentable = presentable as Presentable + eventHandler = currentMessagePresentable?.getPresentation()?.eventHandler + // in-line handling of JavaScript calls + eventHandler?.handleJavascriptMessage("myInappCallback") { content -> + if (content != null) { + println("JavaScript body passed to native callback: $content") + val message: Message? = MessagingUtils.getMessageForPresentable(currentMessagePresentable) + message?.track(content, MessagingEdgeEventType.INTERACT); + } + } +} +``` + +#### Java + +```java +InAppMessageEventHandler eventHandler = null; +Presentable currentMessagePresentable = null; + +@Override +public void onShow(Presentable presentable) { + if (!(presentable.getPresentation() instanceof InAppMessage)) { + return; + } + currentMessagePresentable = (Presentable) presentable; + eventHandler = currentMessagePresentable.getPresentation().getEventHandler(); + // in-line handling of JavaScript calls + eventHandler.handleJavascriptMessage("myInappCallback", content -> { + if (content != null) { + System.out.println("JavaScript body passed to native callback: " + content); + Message message = MessagingUtils.getMessageForPresentable(currentMessagePresentable); + if (message != null) { + message.track(content, MessagingEdgeEventType.INTERACT); + } + } + }); +} +``` + + In the `shouldShowMessage` function of the `MessagingDelegate`, call `public void handleJavascriptMessage(final String name, final AdobeCallback callback)` to register your handler. diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/index.md b/src/pages/edge/adobe-journey-optimizer/public-classes/index.md index 4938805d62..82d4797ec0 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/index.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/index.md @@ -24,3 +24,10 @@ This documents lists details about the public classes and enums available in Mes * [Class - Message](./message.md) * [Enum - MessagingEdgeEventType](./messaging-edge-event-type.md) + +## Code-based experiences + +* [Class - Proposition](./proposition.md) +* [Class - PropositionItem](./proposition-item.md) +* [Class - Surface](./surface.md) +* [Enum - MessagingEdgeEventType](./messaging-edge-event-type.md) diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/message.md b/src/pages/edge/adobe-journey-optimizer/public-classes/message.md index bd53674489..52f005e69c 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/message.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/message.md @@ -99,7 +99,7 @@ iOS ## Android Interface - Message -`InternalMessage` objects implementing this interface are created by the AEPMessaging extension, and passed as the `message` parameter in `MessagingDelegate` interface methods. +The `Message` class has the business logic related to the in-app message to perform actions like sending tracking events on interactions and suppress tracking. If your app implements `PresentationDelegate`, it will receive a `Presentable` object, which is the Mobile Core class containing in-app message view. You will need to get the `Message` object associated with `Presentable` object using the `MessagingUtils.getMessageForPresentable(Presentable)` API. Refer to this [tutorial](../in-app-message/tutorials/messaging-delegate.md) for more details. ## Public functions @@ -115,6 +115,12 @@ void show() ### dismiss + + +This API has been changed in v3.0.0 of Adobe Journey Optimizer extension. + +In earlier versions, this API accepted a parameter `suppressAutoTrack`: If set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. + Signals to the UIService that the message should be removed from the UI. If `autoTrack` is true, calling this method will result in an "decisioning.propositionDismiss" Edge Event being dispatched. @@ -143,12 +149,30 @@ Sets the `Message`'s auto tracking preference. Android - + + +### getAutoTrack + +Returns the `Message`'s auto tracking preference. + + + +Android + + ### evaluateJavascript + + +This API has been removed in v3.0.0 of Adobe Journey Optimizer extension. + +Migrate to use `PresentationDelegate` and use the `InAppMessageEventHandler.evaluateJavascript(String, AdobeCallback)` API instead. Refer to this [tutorial](../in-app-message/tutorials/javascript-from-native/) for more details. + Evaluates the passed in `String` content containing JavaScript code using the `Message`'s webview. `handleJavascriptMessage` must be called with a valid callback before calling `evaluateJavascript` as the body of the message passed from the JavaScript code execution will be returned in the `AdobeCallback` . +For a full guide on how to use `handleJavascriptMessage`, read the guide on [executing JavaScript methods from native code](../in-app-message/tutorials/javascript-from-native.md). + Android @@ -157,11 +181,17 @@ Android ### handleJavascriptMessage + + +This API has been removed in v3.0.0 of Adobe Journey Optimizer extension. + +Migrate to use `PresentationDelegate` and use the `InAppMessageEventHandler.handleJavascriptMessage(String, AdobeCallback)` API instead. Refer to this [tutorial](../in-app-message/tutorials/native-from-javascript/) for more details. + Adds a handler for named JavaScript messages sent from the message's `WebView`. The `AdobeCallback` will contain the body of the message passed from the `WebView`'s JavaScript. -For a full guide on how to use `handleJavascriptMessage`, read the guide on [calling native code from the Javascript of an in-app message](./how-to-call-native-from-javascript.md). +For a full guide on how to use `handleJavascriptMessage`, read the guide on [calling native code from the Javascript of an in-app message](../in-app-message/tutorials/native-from-javascript/). @@ -179,6 +209,12 @@ String getId() ### getParent + + +This API has been removed in v3.0.0 of Adobe Journey Optimizer extension. + +Please use the `MessagingUtils.getMessageForPresentable(Presentable)` API instead. Refer to this [tutorial](../in-app-message/tutorials/messaging-delegate.md) for more details. + Returns the `Object` which created this `Message`. ```java @@ -187,6 +223,12 @@ Object getParent() ### getWebView + + +This API has been removed in v3.0.0 of Adobe Journey Optimizer extension. + +Functionality is no longer supported. + Returns a reference to the message's `WebView` instance, if it exists. ```java diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/proposition-item.md b/src/pages/edge/adobe-journey-optimizer/public-classes/proposition-item.md index 6905f290df..f3fbeb1ff0 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/proposition-item.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/proposition-item.md @@ -92,10 +92,6 @@ iOS ## Android Interface - PropositionItem -### Coming soon - - diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/proposition.md b/src/pages/edge/adobe-journey-optimizer/public-classes/proposition.md index 66ce4a477c..9387c0dda5 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/proposition.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/proposition.md @@ -46,10 +46,6 @@ public lazy var items: [PropositionItem] ## Android Interface - Proposition -### Coming soon - - diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/surface.md b/src/pages/edge/adobe-journey-optimizer/public-classes/surface.md index ea1d93358a..253827bda8 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/surface.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/surface.md @@ -44,9 +44,6 @@ iOS ## Android Interface - Surface -### Coming soon - - \ No newline at end of file diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/message.md b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/message.md index 1d490a2290..3134007668 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/message.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/message.md @@ -38,18 +38,14 @@ public func handleJavascriptMessage(_ name: String, withHandler handler: @escapi * *name*: The name of the message that should be handled by `handler` * *handler*: The method or closure to be called with the body of the message created in the Message's JavaScript - + #### Java ```java -void dismiss(final boolean suppressAutoTrack) +void dismiss() ``` -##### Parameters - -* *suppressAutoTrack*: If set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. - #### Java @@ -61,7 +57,7 @@ void track(final String interaction, final MessagingEdgeEventType eventType) ##### Parameters * *interaction*: A custom `String` value to be recorded in the interaction -* *eventType*: The [`MessagingEdgeEventType`](#enum-messagingedgeeventtype) to be used for the ensuing Edge Event +* *eventType*: The [`MessagingEdgeEventType`](../messaging-edge-event-type.md) to be used for the ensuing Edge Event @@ -76,7 +72,7 @@ void handleJavascriptMessage(final String name, final AdobeCallback call * *name*: The name of the message that should be handled by the `callback` * *callback*: A callback which will be called with the body of the message created in the Message's JavaScript - + #### Java @@ -88,6 +84,14 @@ void setAutoTrack(boolean enabled) * *enabled*: If true, Experience Edge events will automatically be generated when this `Message` is triggered, displayed, or dismissed. + + +#### Java + +```java +boolean getAutoTrack() +``` + #### Java diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/messaging-edge-event-type.md b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/messaging-edge-event-type.md index e9747dbd80..3f88a05460 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/messaging-edge-event-type.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/messaging-edge-event-type.md @@ -2,51 +2,85 @@ noIndex: true --- - + + + + +This enum has been changed in v3.0.0 of Adobe Journey Optimizer extension. + +Please use newly added `DISMISS`, `INTERACT`, `TRIGGER`, `DISPLAY` values in place of `IN_APP_DISMISS`, `IN_APP_INTERACT`, `IN_APP_TRIGGER`, `IN_APP_DISPLAY` from earlier versions. + + #### Java ```java public enum MessagingEdgeEventType { - IN_APP_DISMISS(0), - IN_APP_INTERACT(1), - IN_APP_TRIGGER(2), - IN_APP_DISPLAY(3), PUSH_APPLICATION_OPENED(4), - PUSH_CUSTOM_ACTION(5); - - final int value; + PUSH_CUSTOM_ACTION(5), + DISMISS(6), + INTERACT(7), + TRIGGER(8), + DISPLAY(9); MessagingEdgeEventType(final int value) { this.value = value; } + /** + * @deprecated This method will be removed in future versions. + */ + @Deprecated public int getValue() { return value; } - @Override + public String getPropositionEventType() { + switch (this) { + case DISMISS: + return PROPOSITION_EVENT_TYPE_DISMISS; + case INTERACT: + return PROPOSITION_EVENT_TYPE_INTERACT; + case TRIGGER: + return PROPOSITION_EVENT_TYPE_TRIGGER; + case DISPLAY: + return PROPOSITION_EVENT_TYPE_DISPLAY; + default: + return ""; + } + } + + @NonNull @Override public String toString() { switch (this) { - case IN_APP_DISMISS: - return MessagingConstants.EventDataKeys.Messaging.IAMDetailsDataKeys.EventType.DISMISS; - case IN_APP_INTERACT: - return MessagingConstants.EventDataKeys.Messaging.IAMDetailsDataKeys.EventType.INTERACT; - case IN_APP_TRIGGER: - return MessagingConstants.EventDataKeys.Messaging.IAMDetailsDataKeys.EventType.TRIGGER; - case IN_APP_DISPLAY: - return MessagingConstants.EventDataKeys.Messaging.IAMDetailsDataKeys.EventType.DISPLAY; + case DISMISS: + return PROPOSITION_EVENT_TYPE_DISMISS_STRING; + case INTERACT: + return PROPOSITION_EVENT_TYPE_INTERACT_STRING; + case TRIGGER: + return PROPOSITION_EVENT_TYPE_TRIGGER_STRING; + case DISPLAY: + return PROPOSITION_EVENT_TYPE_DISPLAY_STRING; case PUSH_APPLICATION_OPENED: - return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.OPENED; + return PUSH_NOTIFICATION_EVENT_TYPE_STRING_OPENED; case PUSH_CUSTOM_ACTION: - return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.CUSTOM_ACTION; + return PUSH_NOTIFICATION_EVENT_TYPE_STRING_CUSTOM_ACTION; default: return super.toString(); } } +} ``` - + + + + +This enum has been changed in v5.0.0 of Adobe Journey Optimizer extension. + +Please use newly added values `dismiss`, `interact`, `trigger`, `display` in place of `inappDismiss`, `inappInteract`, `inappTrigger`, `inappDisplay` from earlier versions. + + #### Swift @@ -83,10 +117,10 @@ public enum MessagingEdgeEventType: Int { | Case | String value | | ---- | ------------ | -| IN_APP_DISMISS | `decisioning.propositionDismiss` | -| IN_APP_INTERACT | `decisioning.propositionInteract` | -| IN_APP_TRIGGER | `decisioning.propositionTrigger` | -| IN_APP_DISPLAY | `decisioning.propositionDisplay` | +| DISMISS | `decisioning.propositionDismiss` | +| INTERACT | `decisioning.propositionInteract` | +| TRIGGER | `decisioning.propositionTrigger` | +| DISPLAY | `decisioning.propositionDisplay` | | PUSH_APPLICATION_OPENED | `pushTracking.applicationOpened` | | PUSH_CUSTOM_ACTION | `pushTracking.customAction` | diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/proposition-item.md b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/proposition-item.md index e765d34f99..0db0b2b124 100644 --- a/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/proposition-item.md +++ b/src/pages/edge/adobe-journey-optimizer/public-classes/tabs/proposition-item.md @@ -87,7 +87,7 @@ public Map getJsonContentMap() **Syntax** ```java -public List> getJsonArrayList() +public List> getJsonContentArrayList() ``` diff --git a/src/pages/edge/adobe-journey-optimizer/tutorials/javascript-from-native.md b/src/pages/edge/adobe-journey-optimizer/tutorials/javascript-from-native.md index 0ee50d5991..35ab1fa53b 100644 --- a/src/pages/edge/adobe-journey-optimizer/tutorials/javascript-from-native.md +++ b/src/pages/edge/adobe-journey-optimizer/tutorials/javascript-from-native.md @@ -58,4 +58,4 @@ The test apps in this repository demonstrate executing JavaScript code from an i * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) diff --git a/src/pages/edge/adobe-journey-optimizer/tutorials/messaging-delegate.md b/src/pages/edge/adobe-journey-optimizer/tutorials/messaging-delegate.md index 773673ccb0..81a58be506 100644 --- a/src/pages/edge/adobe-journey-optimizer/tutorials/messaging-delegate.md +++ b/src/pages/edge/adobe-journey-optimizer/tutorials/messaging-delegate.md @@ -81,7 +81,7 @@ The test apps in this repository demonstrate using a `MessagingDelegate`: * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) #### Further reading diff --git a/src/pages/edge/adobe-journey-optimizer/tutorials/native-from-javascript.md b/src/pages/edge/adobe-journey-optimizer/tutorials/native-from-javascript.md index fceb087ef9..fc928ef29c 100644 --- a/src/pages/edge/adobe-journey-optimizer/tutorials/native-from-javascript.md +++ b/src/pages/edge/adobe-journey-optimizer/tutorials/native-from-javascript.md @@ -80,4 +80,4 @@ The test apps in this repository demonstrate calling native code from JavaScript * [Swift](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoApp) * [Objective-C](https://github.com/adobe/aepsdk-messaging-ios/tree/main/TestApps/MessagingDemoAppObjC) -* [Java](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) +* [Kotlin](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) diff --git a/src/pages/edge/identity-for-edge-network/tabs/faq.md b/src/pages/edge/identity-for-edge-network/tabs/faq.md index a386df50b6..9a5b71d707 100644 --- a/src/pages/edge/identity-for-edge-network/tabs/faq.md +++ b/src/pages/edge/identity-for-edge-network/tabs/faq.md @@ -9,7 +9,7 @@ import Alerts from '/src/pages/resources/alerts.md' 1. Add the Mobile Core and Edge extensions to your project using the app's Gradle file. ```java -implementation platform('com.adobe.marketing.mobile:sdk-bom:2.+') +implementation platform('com.adobe.marketing.mobile:sdk-bom:3.+') implementation 'com.adobe.marketing.mobile:core' implementation 'com.adobe.marketing.mobile:edge' implementation 'com.adobe.marketing.mobile:edgeidentity' diff --git a/src/pages/home/current-sdk-versions.md b/src/pages/home/current-sdk-versions.md index a05e517a11..6da192ad3a 100644 --- a/src/pages/home/current-sdk-versions.md +++ b/src/pages/home/current-sdk-versions.md @@ -48,8 +48,8 @@ The Android BOM (Bill of Materials) artifact has been released to Maven Central. | [Consent for Edge Network](../edge/consent-for-edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgeconsent.svg?logo=android&logoColor=white&label=edgeconsent&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgeconsent) | [GitHub](https://github.com/adobe/aepsdk-edgeconsent-android) | [Test app](https://github.com/adobe/aepsdk-edgeconsent-android/tree/main/code/app) | | [Media for Edge Network](../edge/media-for-edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgemedia.svg?logo=android&logoColor=white&label=edgemedia&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgemedia) | [GitHub](https://github.com/adobe/aepsdk-edgemedia-android) | [Test app](https://github.com/adobe/aepsdk-edgemedia-android/tree/main/code/testappkotlin) | | [Edge Bridge](../solution/adobe-analytics/migrate-to-edge-network.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgebridge.svg?logo=android&logoColor=white&label=edgebridge&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgebridge) | [GitHub](https://github.com/adobe/aepsdk-edgebridge-android) | [Test app](https://github.com/adobe/aepsdk-edgebridge-android/tree/main/code/app) | -| [Adobe Journey Optimizer](../edge/adobe-journey-optimizer/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/messaging.svg?logo=android&logoColor=white&label=messaging&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/messaging) | [GitHub](https://github.com/adobe/aepsdk-messaging-android) | [Test app](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/app) | -| [Adobe Journey Optimizer - Decisioning](../edge/adobe-journey-optimizer-decisioning/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/optimize.svg?logo=android&logoColor=white&label=optimize&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/optimize) | [GitHub](https://github.com/adobe/aepsdk-optimize-android) | [Test app](https://github.com/adobe/aepsdk-optimize-android/tree/main/code/app) | +| [Adobe Journey Optimizer](../edge/adobe-journey-optimizer/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/messaging.svg?logo=android&logoColor=white&label=messaging&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/messaging) | [GitHub](https://github.com/adobe/aepsdk-messaging-android) | [Test app](https://github.com/adobe/aepsdk-messaging-android/tree/main/code/testapp) | +| [Adobe Journey Optimizer - Decisioning](../edge/adobe-journey-optimizer-decisioning/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/optimize.svg?logo=android&logoColor=white&label=optimize&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/optimize) | [GitHub](https://github.com/adobe/aepsdk-optimize-android) | [Test app](https://github.com/adobe/aepsdk-optimize-android/tree/main/code/testapp) | | [Places Service](https://experienceleague.adobe.com/docs/places/using/home.html) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/places.svg?logo=android&logoColor=white&label=places&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/places) | [GitHub](https://github.com/adobe/aepsdk-places-android) | [Test app](https://github.com/adobe/aepsdk-places-android/tree/main/code/testapp) | | [Adobe Analytics](../solution/adobe-analytics/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/analytics.svg?logo=android&logoColor=white&label=analytics&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/analytics) | [GitHub](https://github.com/adobe/aepsdk-analytics-android) | [Test app](https://github.com/adobe/aepsdk-analytics-android/tree/main/code/testapp) | | [Adobe Analytics - Media Analytics for Audio & Video](../solution/adobe-media-analytics/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/media.svg?logo=android&logoColor=white&label=media&style=flat-square)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/media) | [GitHub](https://github.com/adobe/aepsdk-media-android) | [Test app](https://github.com/adobe/aepsdk-media-android/tree/main/code/testapp) | diff --git a/src/pages/resources/migration/android/index.md b/src/pages/resources/migration/android/index.md index 020b7e4947..bc78237981 100644 --- a/src/pages/resources/migration/android/index.md +++ b/src/pages/resources/migration/android/index.md @@ -2,6 +2,10 @@ This document provides a collection of resources to help you migrate between various versions of the Adobe Experience Platform SDKs for Android. +## Migrate to Adobe Experience Platform 3.x SDKs for Android + +Learn how to [migrate to Adobe Experience Platform 3.x SDKs for Android](./migrate-to-3x.md) from Experience Platform 2.x SDKs for Android. + ## Migrate to Adobe Experience Platform 2.x SDKs for Android Learn how to [migrate to Adobe Experience Platform 2.x SDKs for Android](./migrate-to-2x.md) from Experience Platform 1.x SDKs for Android. diff --git a/src/pages/resources/migration/android/migrate-to-3x.md b/src/pages/resources/migration/android/migrate-to-3x.md new file mode 100644 index 0000000000..7b1945b0a0 --- /dev/null +++ b/src/pages/resources/migration/android/migrate-to-3x.md @@ -0,0 +1,282 @@ +# 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 + +
+ +
+ +descriptive text + +
+ +### Android extensions + +
+ +| Extension | Version | +|---|---| +| [Mobile Core](../../../home/base/mobile-core/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/core.svg?logo=android&logoColor=white&label=core&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/core) | +| [Signal](../../../home/base/mobile-core/signal/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/signal.svg?logo=android&logoColor=white&label=signal&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/signal) | +| [Lifecycle](../../../home/base/mobile-core/lifecycle/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/lifecycle.svg?logo=android&logoColor=white&label=lifecycle&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/lifecycle) | +| [Identity](../../../home/base/mobile-core/identity/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/identity.svg?logo=android&logoColor=white&label=identity&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/identity) | +| [Profile](../../../home/base/profile/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/userprofile.svg?logo=android&logoColor=white&label=userprofile&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/userprofile) | +| [Adobe Experience Platform Assurance](../../../home/base/assurance/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/assurance.svg?logo=android&logoColor=white&label=assurance&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/assurance) | +| [Adobe Experience Platform Edge Network](../../../edge/edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edge.svg?logo=android&logoColor=white&label=edge&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edge) | +| [Identity for Edge Network](../../../edge/identity-for-edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgeidentity.svg?logo=android&logoColor=white&label=edgeidentity&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgeidentity) |adobe/aepsdk-edgeidentity-android) | +| [Consent for Edge Network](../../../edge/consent-for-edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgeconsent.svg?logo=android&logoColor=white&label=edgeconsent&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgeconsent) | +| [Media for Edge Network](../../../edge/media-for-edge-network/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgemedia.svg?logo=android&logoColor=white&label=edgemedia&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgemedia) | +| [Edge Bridge](../../../solution/adobe-analytics/migrate-to-edge-network.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/edgebridge.svg?logo=android&logoColor=white&label=edgebridge&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/edgebridge) | +| [Adobe Journey Optimizer](../../../edge/adobe-journey-optimizer/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/messaging.svg?logo=android&logoColor=white&label=messaging&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/messaging) | +| [Adobe Journey Optimizer - Decisioning](../../../edge/adobe-journey-optimizer-decisioning/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/optimize.svg?logo=android&logoColor=white&label=optimize&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/optimize) | +| [Places Service](https://experienceleague.adobe.com/docs/places/using/home.html) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/places.svg?logo=android&logoColor=white&label=places&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/places) | +| [Adobe Analytics](../../../solution/adobe-analytics/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/analytics.svg?logo=android&logoColor=white&label=analytics&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/analytics) | +| [Adobe Analytics - Media Analytics for Audio & Video](../../../solution/adobe-media-analytics/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/media.svg?logo=android&logoColor=white&label=media&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/media) | +| [Adobe Target](../../../solution/adobe-target/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/target.svg?logo=android&logoColor=white&label=target&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/target) | +| [Adobe Campaign Standard](../../../solution/adobe-campaign-standard/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/campaign.svg?logo=android&logoColor=white&label=campaign&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/campaign) | +| [Adobe Campaign Classic](../../../solution/adobe-campaign-classic/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/campaignclassic.svg?logo=android&logoColor=white&label=campaignclassic&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/campaignclassic) | +| [Adobe Audience Manager](../../../solution/adobe-audience-manager/index.md) | [![Maven Central](https://img.shields.io/maven-central/v/com.adobe.marketing.mobile/audience.svg?logo=android&logoColor=white&label=audience&style=flat-square&versionPrefix=3)](https://mvnrepository.com/artifact/com.adobe.marketing.mobile/audience) | + +## 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](#update-dependencies) +2. [Update SDK initialization](#update-sdk-initialization) +3. [Handle API migration and breaking changes](#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. + + + +Using dynamic dependency versions is not recommended for production apps. Refer to this [page](../../../resources/manage-gradle-dependencies.md) for managing Gradle dependencies. + +```java +dependencies { + // implementation '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 '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](https://mvnrepository.com/artifact/com.adobe.marketing.mobile). + +### 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](./migrate-to-2x.md#update-sdk-initialization) 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](#update-sdk-initialization) section for more details. + +#### MobileCore + +| Removed API | Alternative API | +| :------------- | :-------------- | +| MobileCore.start(AdobeCallback)| [MobileCore.registerExtensions](../../../home/base/mobile-core/api-reference.md#registerextensions) registers extensions and starts event processing by default | +| MobileCore.dispatchEventWithResponseCallback(Event, AdobeCallbackWithError)| Use [MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError)](../../../home/base/mobile-core/api-reference.md#dispatch--dispatcheventwithresponsecallback) to explicitly specify a timeout | +| MessagingDelegate | Refer to this [page](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) 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](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/code/core/src/phone/java/com/adobe/marketing/mobile/services/Log.java) | +| MobileCore.registerExtension(Class, ExtensionErrorCallback) | [MobileCore.registerExtensions](../../../home/base/mobile-core/api-reference.md#registerextensions) | +| MobileCore.dispatchEvent(Event, ExtensionErrorCallback)| [MobileCore.dispatch(Event)](../../../home/base/mobile-core/api-reference.md#dispatch--dispatchevent) , [MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError)](../../../home/base/mobile-core/api-reference.md#dispatch--dispatcheventwithresponsecallback) | +| MobileCore.dispatchEvent(Event, AdobeCallback, ExtensionErrorCallback)| [MobileCore.dispatchEventWithResponseCallback(Event, long, AdobeCallbackWithError)](../../../home/base/mobile-core/api-reference.md#dispatch--dispatcheventwithresponsecallback) | +| MobileCore.dispatchResponseEvent(Event, Event, ExtensionErrorCallback) | Use **Event.Builder.inResponseToEvent(Event)** to create a response event | +| Event.copy() | Use [Event.Builder()](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#creating-an-event) 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)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#updating-shared-state), [ExtensionApi.createPendingSharedState(Event)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#creating-and-updating-a-pending-shared-state) | +| ExtensionApi.setXDMSharedEventState(Map, Event, ExtensionErrorCallback)| [ExtensionApi.createXDMSharedState(Map, Event)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#updating-xdm-shared-state), [ExtensionApi.createXDMPendingSharedState(Event)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#creating-and-updating-a-pending-xdm-shared-state) | +| ExtensionApi.getSharedEventState(String, ExtensionErrorCallback)| [ExtensionApi.getSharedState(String, Event, boolean, SharedStateResolution)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#reading-shared-state-from-another-extension) | +| ExtensionApi.getXDMSharedEventState(String, Event, ExtensionErrorCallback)| [ExtensionApi.getXDMSharedState(String, Event, boolean, SharedStateResolution)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#reading-xdm-shared-state-from-another-extension) | +| ExtensionApi.clearSharedEventStates(ExtensionErrorCallback)| Use [ExtensionApi.createSharedState(Map, Event)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#updating-shared-state) with an empty state | +| ExtensionApi.clearXDMSharedEventStates(ExtensionErrorCallback)| Use [ExtensionApi.createXDMSharedState(Map, Event)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#updating-xdm-shared-state) with an empty state | +| ExtensionApi.registerEventListener(String, String, Class, ExtensionErrorCallback)| [ExtensionApi.registerEventListener(String, String,ExtensionEventListener)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#listener-example)| +| ExtensionApi.registerWildcardEventListener(Class, ExtensionErrorCallback) | [ExtensionApi.registerEventListener(String, String, ExtensionEventListener)](https://github.com/adobe/aepsdk-core-android/blob/v3.0.0-core/Documentation/EventHub/BuildingExtensions.md#wildcard-listeners) | +| 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](../../../home/base/profile/api-reference.md#updateuserattributes) | +| UserProfile.removeUserAttribute | [UserProfile.removeUserAttributes](../../../home/base/profile/api-reference.md#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](https://experienceleague.adobe.com/en/docs/analytics/implementation/aep-edge/data-var-mapping). | +| 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: + +```kotlin +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: + +```json +{ + "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: + +```kotlin +MobileCore.trackState("view name", mapOf("&&events" to "event5,event2=2")) +``` + + The resulting Experience Event has the following payload: + +```json +{ + "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](https://developer.adobe.com/client-sdks/resources/major-version-alignment/). + +#### Messaging + +| Removed API | Alternative API | +| :------------- | :-------------- | +| Message.dismiss(boolean suppressAutoTrack) | [Message.dismiss()](../../../edge/adobe-journey-optimizer/public-classes/message.md#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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native/) 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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript/) 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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) 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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) for more details| +| MessagingDelegate.onShow(FullscreenMessage) | Migrate to **com.adobe.marketing.mobile.services.ui.PresentationDelegate** and use **PresentationDelegate.onShow(Presentable)**. Refer to this [tutorial](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) for more details| +| MessagingDelegate.onDismiss(FullscreenMessage) | Migrate to **com.adobe.marketing.mobile.services.ui.PresentationDelegate** and use **PresentationDelegate.onDismiss(Presentable)**. Refer to this [tutorial](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) 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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) for more details| + +#### Optimize + +| Removed API | Alternative API | +| :------------- | :-------------- | +| com.adobe.marketing.mobile.optimize.Proposition | [com.adobe.marketing.mobile.optimize.OptimizeProposition](../../../edge/adobe-journey-optimizer-decisioning/api-reference#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](../../../edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate/) 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: + +```text +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](#update-dependencies) using Adobe SDK BOM. + +### Why do I see installation instructions related to older SDK versions on Data Collection UI? + +Upgrade the extensions within the mobile property in the Data Collection UI to see latest installation instructions for the mobile platform extensions. diff --git a/src/pages/resources/migration/ios/migrate-to-5x.md b/src/pages/resources/migration/ios/migrate-to-5x.md index 1e62880893..9d19434b0f 100644 --- a/src/pages/resources/migration/ios/migrate-to-5x.md +++ b/src/pages/resources/migration/ios/migrate-to-5x.md @@ -35,7 +35,7 @@ This Mobile SDK version for iOS now supports a minimum iOS version of 12.0 and a If you have implemented Adobe Experience Platform 4.x SDKs for iOS, then this guide will help you understand the steps required to migrate your implementation to the Experience Platform 5.x SDKs. In summary, you'll need to: 1. [Update dependencies](#update-dependencies) -2. [Update outdated API references](#update-outdated-api-references) +2. [Handle API migration and breaking changes](#handle-api-migration-and-breaking-changes) ### Update dependencies @@ -70,7 +70,7 @@ Once the previous command is complete, run `pod install` or `pod update` to upda If you are using Swift Package Manger (SPM) for managing your app dependencies, you can now include the Experience Platform 5.x SDKs either through Xcode UI, or by declaring them as dependencies in the Package.swift project file. For more details, follow the guide for [managing dependencies using Swift Package Manager](../../manage-spm-dependencies.md). -## Update outdated API references +## Handle API migration and breaking changes When updating to the Experience Platform 5.x SDKs, please take note of the following updates for API references. @@ -80,7 +80,7 @@ As of version 5.0.0 of the Adobe Experience Platform Edge Bridge for iOS, the ta | Data | Key path in v4.x | Key path in v5.+ | Description | | --- | --- | --- | --- | -| Action | `data.action` | `data.__adobe.analytics.linkName` | As of v5, set as the custom link name in the Analytics hit. The field `data.__adobe.analytics.linkType` with value `lnk_o` is also automatically included. | +| Action | `data.action` | `data.__adobe.analytics.linkName` | As of v5, 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 v5, 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 v5, there was no special handling of context data prefixed with "&&".

As of v5, 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](https://experienceleague.adobe.com/en/docs/analytics/implementation/aep-edge/data-var-mapping). | @@ -103,7 +103,7 @@ The resulting Experience Event has the following payload: "__adobe": { "analytics": { "linkName": "action name", - "linkType": "lnk_o", + "linkType": "other", "cp": "foreground", "products": ";Running Shoes;1;69.95;event1|event2=55.99;eVar1=12345", "contextData":{ @@ -158,4 +158,4 @@ For examples see [handleNotificationResponse](./../../../edge/adobe-journey-opti #### Optimize -The `Proposition` class has been renamed to [`OptimizeProposition`](./../../../edge/adobe-journey-optimizer-decisioning/api-reference/#propositionoptimizeproposition). All references should be updated accordingly. +The `Proposition` class has been renamed to [`OptimizeProposition`](./../../../edge/adobe-journey-optimizer-decisioning/api-reference#optimizeproposition). All references should be updated accordingly. diff --git a/src/pages/solution/adobe-analytics/migrate-to-edge-network.md b/src/pages/solution/adobe-analytics/migrate-to-edge-network.md index 94bc0e39a1..0a05874b91 100644 --- a/src/pages/solution/adobe-analytics/migrate-to-edge-network.md +++ b/src/pages/solution/adobe-analytics/migrate-to-edge-network.md @@ -37,7 +37,7 @@ Other foundational extensions include the [Consent for Edge Network extension](. | Steps | Edge Network extension | Edge Bridge extension | | ----------- | ----------- | ----------- | -| 1. [Set up an XDM schema](https://experienceleague.adobe.com/docs/experience-platform/xdm/home.html). Experience Data Model (XDM) is the open and publicly documented data model standard created by Adobe to standardize data collection, and is used across applications that leverage Experience Platform.
**NOTE:** Take advantage of [automatic Analytics variable mapping](https://experienceleague.adobe.com/docs/analytics/implementation/aep-edge/variable-mapping.html) of XDM fields to Analytics dimensions by using the Adobe managed XDM schemas for Lifecycle, Media, Commerce, and more.| ✅ | ✅ | +| 1. [Set up an XDM schema](https://experienceleague.adobe.com/docs/experience-platform/xdm/home.html). Experience Data Model (XDM) is the open and publicly documented data model standard created by Adobe to standardize data collection, and is used across applications that leverage Experience Platform.
**NOTE:** Take advantage of [automatic Analytics variable mapping](https://experienceleague.adobe.com/docs/analytics/implementation/aep-edge/variable-mapping.html) of XDM fields to Analytics dimensions by using the Adobe managed XDM schemas for Lifecycle, Media, Commerce, and more.| ✅ | | | 2. [Configure a datastream](https://experienceleague.adobe.com/docs/experience-platform/edge/datastreams/overview.html). A datastream is the server-side configuration used when implementing the Experience Platform Mobile SDK. | ✅ | ✅ | | 3. **Add the Adobe Analytics service** to your datastream. The datastream controls both whether and how data is sent to Adobe Analytics. You will need your Analytics report suite ID (RSID) for this step. | ✅ | ✅ | | 4. **Install the *Edge Network* and *Identity for Edge Network extensions*** in the mobile property (tag) in Data Collection UI, and set the datastream in the Edge Network extension configuration. | ✅ | ✅ | @@ -46,7 +46,7 @@ Other foundational extensions include the [Consent for Edge Network extension](. | 6. **Remove the Analytics extension** dependency and extension registration from your mobile app code.
**NOTE:** You should still keep the Analytics extension installed in the mobile property (tag) to ensure published versions of your app (pre-migration) continue to work seamlessly. | ✅ | ✅ | | 7 .**Use Edge.sendEvent API** to send data in XDM format to Edge Network based on the schema you have defined. | ✅ | | | 8. **Keep existing MobileCore.trackAction / MobileCore.trackState API calls** to send data in context data format to Experience Platform.| | ✅ | -| 9. **(Optional) Map your context data to XDM** in Data Prep for Data Collection if required for other services. Not required for Analytics.| | ✅ | +| 9. **(Optional) Map your context data to XDM** in Data Prep for Data Collection if required for other services. Not required for Analytics.
**Note:** Mapping using Data Prep for Data Collection requires an [XDM schema](https://experienceleague.adobe.com/docs/experience-platform/xdm/home.html) to be configured for your datastream.| | ✅ | ### Implement the Edge Network extension diff --git a/src/pages/solution/adobe-campaign-classic/api-reference.md b/src/pages/solution/adobe-campaign-classic/api-reference.md index 1fd8a1c50f..f4b7a13421 100644 --- a/src/pages/solution/adobe-campaign-classic/api-reference.md +++ b/src/pages/solution/adobe-campaign-classic/api-reference.md @@ -87,6 +87,10 @@ iOS ## Other public classes + + +Push template functionality and the following public classes are only available in Adobe Campaign Classic Android SDK version from 2.1.0 through the next major version release. + ### AEPMessagingService #### handleRemoteMessage diff --git a/src/pages/solution/adobe-campaign-classic/push-templates/basic.md b/src/pages/solution/adobe-campaign-classic/push-templates/basic.md index a45207184e..6a7e199e04 100644 --- a/src/pages/solution/adobe-campaign-classic/push-templates/basic.md +++ b/src/pages/solution/adobe-campaign-classic/push-templates/basic.md @@ -11,6 +11,10 @@ import Tabs from './tabs/basic.md' # Push template - basic + + +Push template functionality is only available in Adobe Campaign Classic Android SDK version 2.1.0 through the next major version release. + Templates below show all available properties in their respective payloads for FCM (Android) and APNS (iOS). diff --git a/src/pages/solution/adobe-campaign-classic/push-templates/carousel.md b/src/pages/solution/adobe-campaign-classic/push-templates/carousel.md index 3f25c80483..6940b8513c 100644 --- a/src/pages/solution/adobe-campaign-classic/push-templates/carousel.md +++ b/src/pages/solution/adobe-campaign-classic/push-templates/carousel.md @@ -11,6 +11,10 @@ import Tabs from './tabs/carousel.md' # Push template - carousel + + +Push template functionality is only available in Adobe Campaign Classic Android SDK version 2.1.0 through the next major version release. + Templates below show all available properties in their respective payloads for FCM (Android) and APNS (iOS). diff --git a/src/pages/solution/adobe-campaign-classic/push-templates/index.md b/src/pages/solution/adobe-campaign-classic/push-templates/index.md index 637c5bc8eb..22da9c6d9c 100644 --- a/src/pages/solution/adobe-campaign-classic/push-templates/index.md +++ b/src/pages/solution/adobe-campaign-classic/push-templates/index.md @@ -9,6 +9,10 @@ keywords: # Adobe Campaign Classic - push templates + + +Push template functionality is only available in Adobe Campaign Classic Android SDK version 2.1.0 through the next major version release. + This document outlines out of the box push templates supported in Adobe Campaign Classic extension. | **Template Name** | **Availability** | **Description** | diff --git a/src/pages/solution/adobe-campaign-classic/tabs/api-reference.md b/src/pages/solution/adobe-campaign-classic/tabs/api-reference.md index b730fce605..c61475a7ff 100644 --- a/src/pages/solution/adobe-campaign-classic/tabs/api-reference.md +++ b/src/pages/solution/adobe-campaign-classic/tabs/api-reference.md @@ -317,7 +317,7 @@ func application(_ application: UIApplication, didReceiveRemoteNotification user -## _**Requires extension version v2.1.0+**_ +## _**Requires extension version v2.1.0 through the next major version release **_ Builds an `AEPPushPayload` with data extracted from a `RemoteMessage`'s payload. The built `AEPPushPayload` is then used to construct a `Notification`. diff --git a/src/pages/solution/adobe-campaign-standard/tabs/index.md b/src/pages/solution/adobe-campaign-standard/tabs/index.md index d126d873ef..bf5a35f277 100644 --- a/src/pages/solution/adobe-campaign-standard/tabs/index.md +++ b/src/pages/solution/adobe-campaign-standard/tabs/index.md @@ -432,7 +432,7 @@ public void onCreate(Bundle savedInstanceState) { // add url string to Intent object mappings // e.g. urlToIntentMap.put("https://validUrl.com", new Intent()); if (data != null) { - ServiceProvider.getInstance().setURIHandler(new URIHandler() { + ServiceProvider.getInstance().getUriService().setUriHandler(new URIHandler() { @Override public Intent getURIDestination(String uri) { return urlToIntentMap.get(uri);