diff --git a/gatsby-config.js b/gatsby-config.js index efce9dd634..74b9de96ca 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -143,37 +143,104 @@ module.exports = { path: "/edge/adobe-journey-optimizer/api-reference" }, { - title: "Release notes", - path: "/edge/adobe-journey-optimizer/release-notes" + title: "Push Notification", + path: "/edge/adobe-journey-optimizer/push-notification", + pages: [ + { + title: "iOS", + path: "/edge/adobe-journey-optimizer/push-notification/ios/api-reference", + pages: [ + { + title: "API reference", + path: "/edge/adobe-journey-optimizer/push-notification/ios/api-reference" + }, + { + title: "Display Rich Notifications", + path: "/edge/adobe-journey-optimizer/push-notification/ios/display-rich-notifications" + } + ] + }, + { + title: "Android", + path: "/edge/adobe-journey-optimizer/push-notification/android/automatic-display-and-tracking", + pages: [ + { + title: "Automatic display and tracking", + path: "/edge/adobe-journey-optimizer/push-notification/android/automatic-display-and-tracking" + }, + { + title: "Manual display and tracking", + path: "/edge/adobe-journey-optimizer/push-notification/android/manual-display-and-tracking" + } + ] + }, + { + title: "Payload Keys", + path: "/edge/adobe-journey-optimizer/push-notification/push-payload" + } + ] }, { - title: "Public classes and enums", - path: "/edge/adobe-journey-optimizer/public-classes" + title: "In-App Messaging", + path: "/edge/adobe-journey-optimizer/in-app-message", + pages: [ + { + title: "API reference", + path: "/edge/adobe-journey-optimizer/in-app-message/api-reference" + }, + { + title: "Tutorials", + path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate", + pages: [ + { + title: "Progrmmatically control the display of in-app messages", + path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate" + }, + { + title: "Call native code from the JavaScript of an in-app message", + path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript" + }, + { + title: "Execute Javascript methods from native code", + path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native" + }, + { + title: "Handle URL clicks from an in-app message", + path: "/edge/adobe-journey-optimizer/in-app-message/tutorials/handle-clicks" + } + ] + }, + { + title: "Validate using Assurance", + path: "/edge/adobe-journey-optimizer/in-app-message/validate-messages" + } + ] }, { - title: "Tutorials", - path: "/edge/adobe-journey-optimizer/tutorials", - pages: [{ - title: "Implement a MessagingDelegate", - path: "/edge/adobe-journey-optimizer/tutorials/messaging-delegate" - }, + title: "Public classes and enums", + path: "/edge/adobe-journey-optimizer/public-classes-and-enum", + pages: [ { - title: "Call native code from the JavaScript of an in-app message", - path: "/edge/adobe-journey-optimizer/tutorials/native-from-javascript" + title: "MessagingPushPayload", + path: "/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-push-payload" }, { - title: "Execute Javascript methods from native code", - path: "/edge/adobe-journey-optimizer/tutorials/javascript-from-native" + title: "PushTrackingStatus", + path: "/edge/adobe-journey-optimizer/public-classes-and-enum/push-tracking-status" }, { - title: "Handle URL clicks from an in-app message", - path: "/edge/adobe-journey-optimizer/tutorials/handle-clicks" + title: "Message", + path: "/edge/adobe-journey-optimizer/public-classes-and-enum/message" }, { - title: "Validate in-app messaging using Assurance", - path: "/edge/adobe-journey-optimizer/tutorials/validate-messages" + title: "MessagingEdgeEventType", + path: "/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-edge-event-type" } ] + }, + { + title: "Release notes", + path: "/edge/adobe-journey-optimizer/release-notes" } ] }, diff --git a/src/pages/edge/adobe-journey-optimizer/api-reference.md b/src/pages/edge/adobe-journey-optimizer/api-reference.md index ef97efa908..9bfd7ba780 100644 --- a/src/pages/edge/adobe-journey-optimizer/api-reference.md +++ b/src/pages/edge/adobe-journey-optimizer/api-reference.md @@ -25,20 +25,6 @@ iOS -## handleNotificationResponse - -The handleNotificationResponse function transmits the push notification interaction feedback. - - - -Android - - - -iOS - - - ## registerExtension @@ -51,41 +37,19 @@ Android -## refreshInAppMessages - - - -By default, the SDK will automatically fetch in-app message definitions from the remote at the time the Messaging extension is registered. This generally happens once per app lifecycle. - -Some use cases may require the client to request an update from the remote more frequently. Calling the following API will force the Messaging extension to get an updated definition of messages from the remote: - - - -Android - - - -iOS - - - -## setPushIdentifier - - - -Although this API is provided in Mobile Core, the use of this API is required and leveraged by the Adobe Journey Optimizer extension to sync provided push tokens with Adobe Experience Platform services. +## handleNotificationResponse -The setPushIdentifier API sets the push token, allowing you to sync it with Profile in Adobe Experience Platform. +The handleNotificationResponse function transmits the push notification interaction feedback. Android - + iOS - + ## addPushTrackingDetails @@ -95,42 +59,42 @@ The addPushTrackingDetails API is used to update a pending intent with important Calling this API is mandatory, so the pending intent can be used while tracking push notification interactions. - + Android -## Public classes - -### MessagingPushPayload - -`MessagePushPayload` is a helper class for extracting the data payload attributes from `RemoteMessage`, which are used while creating the push notification. - - - -Android +iOS - + -### Public APIs +## refreshInAppMessages -Public APIs are used to get attributes from the push payload, which are used while creating the push notification. +Calling refreshInAppMessages API will force the Messaging extension to get an updated definition of messages from the remote. - + -Android +#### Android - +```kotlin +Messaging.refreshInAppMessages() +``` -### Payload keys +#### Android - +```java +Messaging.refreshInAppMessages(); +``` -Android +#### iOS - +```swift +Messaging.refreshInAppMessages() +``` -iOS +#### iOS - +```objc +[AEPMobileMessaging refreshInAppMessages]; +``` \ No newline at end of file diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/api-reference.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/api-reference.md new file mode 100644 index 0000000000..0bc77f0f7e --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/api-reference.md @@ -0,0 +1,47 @@ +--- +title: In-App Message - API Reference +description: This document lists the public APIs available in the Messaging extension for implementing in-app messaging. +keywords: +- Adobe Journey Optimizer +- API reference +- Messaging +- In-App Message +--- + +# In-App Messaging - API reference + +This document lists the public APIs available in the Messaging extension for implementing in-app messaging. + +## refreshInAppMessages + + + +By default, the SDK will automatically fetch in-app message definitions from the remote at the time the Messaging extension is registered. This generally happens once per app lifecycle. + +Some use cases may require the client to request an update from the remote more frequently. Calling the following API will force the Messaging extension to get an updated definition of messages from the remote: + + + +#### Android + +```kotlin +Messaging.refreshInAppMessages() +``` + +#### Android + +```java +Messaging.refreshInAppMessages(); +``` + +#### iOS + +```swift +Messaging.refreshInAppMessages() +``` + +#### iOS + +```objc +[AEPMobileMessaging refreshInAppMessages]; +``` diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/iam-simulation.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/iam-simulation.png new file mode 100644 index 0000000000..2d547e5deb Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/iam-simulation.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/install-iam-plugin.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/install-iam-plugin.png new file mode 100644 index 0000000000..780a632851 Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/install-iam-plugin.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-configuration.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-configuration.png new file mode 100644 index 0000000000..2db30cc960 Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-configuration.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-request.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-request.png new file mode 100644 index 0000000000..2bc6ff3b7c Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-request.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response-payload.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response-payload.png new file mode 100644 index 0000000000..8762692228 Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response-payload.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response.png b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response.png new file mode 100644 index 0000000000..edbb2d5427 Binary files /dev/null and b/src/pages/edge/adobe-journey-optimizer/in-app-message/assets/validate-messages/message-response.png differ diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/index.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/index.md new file mode 100644 index 0000000000..e2f7ae3db3 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/index.md @@ -0,0 +1,33 @@ +--- +title: In-app messaging +description: This document guides you to integrating in-app messaging in your application. +keywords: +- Adobe Journey Optimizer +- Guide +- Messaging +- Tutorial +--- + +# In-App Messaging + +This document guides you to integrating in-app messaging in your application. + +## API reference + +* [In-App Messaging APIs](./api-reference.md) + +## Tutorials + +* [Programmatically control the display of in-app messages](./messaging-delegate.md) +* [Call native code from the JavaScript of an in-app message](./native-from-javascript.md) +* [Execute JavaScript code in an in-app message from native code](./javascript-from-native.md) +* [Handle URL clicks from an in-app message](./handle-clicks.md) + +## Public Classes and Enums + +* [Class - Message](../public-classes-and-enum/message.md) +* [Enum - MessagingEdgeEventType](../public-classes-and-enum/messaging-edge-event-type.md) + +## Validation + +* [Validate in-app messaging using Assurance](./validate-messages.md) diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/handle-clicks.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/handle-clicks.md new file mode 100644 index 0000000000..af69987771 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/handle-clicks.md @@ -0,0 +1,104 @@ +--- +title: Handle URL clicks from an in-app message +description: A tutorial that explains how you can handle URL clicks from an in-app message. +keywords: +- Adobe Journey Optimizer +- Guide +- In-app message +- Messaging +- Tutorial +- URL clicks +--- + +# Handle URL clicks from an in-app message + +When a link is clicked in an in-app message, the `FullscreenMessageDelegate` is responsible for handling behavior. + +If the scheme used in the link **is not** `adbinapp://`, the link will open in the containing WKWebView (iOS) or WebView (Android) - this is default behavior. + +If the scheme used in the link **is** `adbinapp://`, the following behavior may occur: + +* The in-app message is dismissed +* An interaction event is sent to Experience Edge +* The default animation is overridden +* The URL will be opened by the OS, potentially resulting in: + * The link being opened by the device's default web browser + * Opening of a deeplink + +## Dismiss the in-app message + +In order for the SDK to remove the view containing an in-app message from the UI, the clicked link must have a host of `dismiss`. + +The example below is a link that will dismiss the current in-app message: + +```shell +adbinapp://dismiss +``` + +## Send a message interaction event to Experience Edge + +Adding a URL variable named `interaction` will cause the SDK to send an Experience Event to the Adobe Experience Edge. + +The example below will dismiss the current in-app message and send a `decisioning.propositionInteract` event to edge with an action of `imageLiked`: + +```shell +adbinapp://dismiss?interaction=imageLiked +``` + +## Override the default dismiss animation + +Adding a URL variable named `animate` will cause the SDK to override the dismiss animation for the message. + +The example below will dismiss the current in-app message, and override the animation so the message exits to the right side of the screen: + +```shell +adbinapp://dismiss?animate=right +``` + +Below is a list of valid values for `animate`: + +| Value | Description | +| ----- | ----------- | +| none | Message is removed with no animation | +| left | Message animates off the screen to the **left** when dismissed | +| right | Message animates off the screen to the **right** when dismissed | +| top | Message animates off the screen to the **top** when dismissed | +| bottom | Message animates off the screen to the **bottom** when dismissed | + +If the value for `animate` is empty, or if it doesn't match one of the above valid values, an animation of `none` will be used. + +## Open a link from the URL + +If the value for a URL variable named `link` contains a valid URL, the SDK will open the link using the OS-defined API. + +### Open location in the default web browser + +If the provided URL does not contain a custom scheme, the URL will be loaded in the device's default web browser. + +The example below will dismiss the current in-app message, send a `decisioning.propositionInteract` event to edge with an action of `adobe`, and open the adobe.com website in the default web browser for the user's device: + +```shell +adbinapp://dismiss?interaction=adobe&link=https%3A%2F%2Fwww.adobe.com%3Fkey%3Dvalue +``` + + + +The `link` parameter must be URL encoded. If you are setting this value in the AJO message authoring UI, the value will automatically be encoded. If your message is custom HTML, you must encode the value manually. + +### Open a deeplink + + + +Android deeplinks require intent filters to be added in the app manifest to correctly handle deeplink URLs. Please see the [Android developer documentation](https://developer.android.com/training/app-links/deep-linking) for more information. + + + +iOS deeplinks require a custom URL scheme to be setup in the application's `info` tab within Xcode to correctly handle deeplink URLs. Please see the [Apple developer documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for more information. + +If the provided URL contains a custom scheme, the app that handles the custom scheme will be launched. + +The example below will dismiss the current in-app message, then launch an app owned by the same developer which handles the scheme `myAppScheme`: + +```shell +adbinapp://dismiss?link=myAppScheme://deeplinked +``` 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 new file mode 100644 index 0000000000..0ee50d5991 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/javascript-from-native.md @@ -0,0 +1,61 @@ +--- +title: Execute JavaScript methods from native code +description: A tutorial that explains how to execute JavaScript in an in-app message from native code. +keywords: +- Adobe Journey Optimizer +- Guide +- JavaScript event +- Messaging +- Messaging delegate +- Tutorial +--- + +import Tabs from './tabs/javascript-from-native.md' + +# Execute JavaScript methods from native code + +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) +* [Call the JavaScript method](#call-the-javascript-method) + +## Implement and assign a `MessagingDelegate` + +To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `MessagingDelegate`. + +For more detailed instructions on implementing and using a MessagingDelegate, please read the [tutorial on using MessagingDelegate](./messaging-delegate.md). + +## Obtain a reference to the web view + +In the `shouldShowMessage` function of the `MessagingDelegate`, get a reference to the web view used by the message. + + + +Android + + + +iOS + + + +## Call the JavaScript method + + + +Android + + + +iOS + + + +## Examples + +The test apps in this repository demonstrate executing JavaScript code from an in-app message's webview: + +* [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) 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 new file mode 100644 index 0000000000..70ff31d2b9 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/messaging-delegate.md @@ -0,0 +1,90 @@ +--- +title: Programmatically control the display of in-app messages +description: A guide that explains how to use a Messaging delegate to programmatically control the display of in-app messages. +keywords: +- Adobe Journey Optimizer +- Guide +- In-app messages +- Messaging +- Tutorial +--- + +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. + +## Register the delegate + + + +Android + + + +iOS + + + +## MessagingDelegate definition + + + +Android + + + +iOS + + + +## Retrieve the `Message` object + + + +Android + + + +iOS + + + +## Controlling when a message should be shown to the end user + + + +Android + + + +iOS + + + +### Integrating the message into an existing UI + + + +Android + + + +iOS + + + +## Examples + +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) + +#### Further reading + +* [More information on how to use the Message object](../../public-classes-and-enum/message.md) +* [Call native code from the JavaScript of an in-app message](./native-from-javascript.md) +* [Execute JavaScript code in an in-app message from native code](./javascript-from-native.md) 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 new file mode 100644 index 0000000000..fceb087ef9 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/native-from-javascript.md @@ -0,0 +1,83 @@ +--- +title: Native handling of JavaScript events +description: A guide explaining how you can handle JavaScript events from in-app message interactions natively within your application. +keywords: +- Adobe Journey Optimizer +- Guide +- JavaScript event +- Messaging +- Messaging delegate +- Tutorial +--- + +import Tabs from './tabs/native-from-javascript.md' + +# Native handling of JavaScript events + +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) +* [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` + +To register a JavaScript event handler with a `Message` object, you will first need to implement and set a `MessagingDelegate`. + +For more detailed instructions on implementing and using a MessagingDelegate, please read the [tutorial on using MessagingDelegate](./messaging-delegate.md). + +## Register a JavaScript handler for your In-App Message + + + +Android + + + +iOS + + + +## Post the JavaScript message from your In-App Message + +Now that the in-app message has been displayed, the final step is to post the JavaScript message. + +Continuing from the previous example, the developer is going to post the `myInappCallback` message from their HTML, which will in turn call the handler previously configured: + +### HTML + +```html + + + + + + + + +``` + +(The above HTML is not representative of a valid in-app message, and is intended only to demonstrate how to post the JavaScript message). + +When the user clicks the button inside of this in-app message, the handler configured in the previous step will be called. The handler will send an Experience Event tracking the interaction, and print the following message to the console: + +```text +JavaScript body passed to native callback: native callbacks are cool! +``` + +## Examples + +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) 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 new file mode 100644 index 0000000000..961593e431 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/javascript-from-native.md @@ -0,0 +1,102 @@ + + +On Android, the web view is represented as `WebView`. + +#### Java + +```java +@Override +public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { + // access to the whole message from the parent + Message message = (Message) fullscreenMessage.getParent(); + + WebView webView = message.getWebView(); + + ... +} +``` + + + +On iOS, the web view is represented as `WKWebView`. + +#### Swift + +```swift +func shouldShowMessage(message: Showable) -> Bool { + // access to the whole message from the parent + let fullscreenMessage = message as? FullscreenMessage + let message = fullscreenMessage?.parent + + let messageWebView = message?.view as? WKWebView + + ... +} +``` + + + +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. + +Further details of this API are explained in the [Android documentation](https://developer.android.com/reference/android/webkit/WebView#evaluateJavascript(java.lang.String,%20android.webkit.ValueCallback%3Cjava.lang.String%3E)) - the example below is provided for the purpose of demonstration: + +#### Java + +```java +@Override +public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { + // access to the whole message from the parent + Message message = (Message) fullscreenMessage.getParent(); + + WebView webView = message.getWebView(); + // webview operations must be run on the ui thread + webView.post(new Runnable() { + @Override + public void run() { + webView.evaluateJavascript("startTimer()", new ValueCallback() { + @Override + public void onReceiveValue(String s) { + // do something with the content + } + }); + } + }); + + ... +} +``` + + + +With a reference to the `WKWebView`, the instance method `evaluateJavaScript(_:completionHandler:)` can now be leveraged to call a JavaScript method. + +Further details of this API are explained in the [Apple documentation](https://developer.apple.com/documentation/webkit/wkwebview/1415017-evaluateJavaScript) - the example below is provided for the purpose of demonstration: + +#### Swift + +```swift +func shouldShowMessage(message: Showable) -> Bool { + // access to the whole message from the parent + let fullscreenMessage = message as? FullscreenMessage + let message = fullscreenMessage?.parent + + // the `shouldShowMessage` delegate method is called on a background thread. + // need to dispatch code that uses the webview back to the main thread. + DispatchQueue.main.async { + let messageWebView = message?.view as? WKWebView + + messageWebView?.evaluateJavaScript("startTimer();") { result, error in + if error != nil { + // handle error + return + } + + if result != nil { + // do something with the result + } + } + } + + ... +} +``` 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 new file mode 100644 index 0000000000..bb5a1d0a55 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/messaging-delegate.md @@ -0,0 +1,313 @@ + + +On Android, the delegate is registered with the Adobe Service Provider. The `ServiceProvider` class maintains an optional property that holds reference to the `FullscreenMessaageDelegate`. + +#### Java + +```java +// defined in public class ServiceProvider +public void setMessageDelegate(MessagingDelegate messageDelegate) +``` + +On Android, the delegate is registered with Mobile Core. The `MobileCore` contains a method to set the`MessagingDelegate` withing the `ServiceProvider` class. + +```java +CustomDelegate myMessagingDelegate = new CustomDelegate(); + +MobileCore.setMessagingDelegate(myMessagingDelegate); +``` + + + +On iOS, the delegate is registered with Mobile Core. The `MobileCore` framework maintains an optional property that holds reference to the `MessagingDelegate`. + +#### Swift + +```swift +/// defined in MobileCore.swift +@objc public static var messagingDelegate: MessagingDelegate? +``` + +Assuming that `InAppMessagingHandler` is a class that implements `MessagingDelegate`, execute the following code to set the delegate in `MobileCore`: + +```swift +let myMessagingDelegate = InAppMessagingHandler() + +MobileCore.messagingDelegate = myMessagingDelegate +``` + + + +The `MessagingDelegate` interface, which is implemented in the `AEPServices` framework, is defined below: + +#### Java + +```java +/** + * UI Message delegate which is used to listen for current message lifecycle events and control if + * the message should be displayed. + */ +public interface MessagingDelegate { + /** + * Invoked when a message is displayed. + * + * @param message {@link FullscreenMessage} that is being displayed + */ + default void onShow(final FullscreenMessage message) { + Log.debug(ServiceConstants.LOG_TAG, "MessagingDelegate", "Fullscreen message shown."); + } + + /** + * Invoked when a message is dismissed. + * + * @param message {@link FullscreenMessage} that is being dismissed + */ + default void onDismiss(final FullscreenMessage message) { + Log.debug(ServiceConstants.LOG_TAG, "MessagingDelegate", "Fullscreen message dismissed."); + } + + /** + * Used to determine if a message should be shown. + * + * @param message {@link FullscreenMessage} that is about to get displayed + * @return true if the message should be displayed, false otherwise + */ + boolean shouldShowMessage(final FullscreenMessage message); + + /** + * Called when the {@link FullscreenMessage} loads a url. + * + * @param url {@code String} being loaded by the {@code FullscreenMessage} + * @param message {@link FullscreenMessage} loading a url {@code String} + */ + default void urlLoaded(final String url, final FullscreenMessage message) { + Log.debug( + ServiceConstants.LOG_TAG, + "MessagingDelegate", + "Fullscreen message loaded url: %s", + url); + } +} +``` + + + +On iOS, the `MessagingDelegate` protocol, which is implemented in the `AEPServices` framework, is defined below: + +#### Swift + +```swift +/// UI Message delegate which is used to listen for current message lifecycle events +@objc(AEPMessagingDelegate) +public protocol MessagingDelegate { + /// Invoked when a message is displayed + /// - Parameters: + /// - message: UIMessaging message that is being displayed + @objc(onShow:) + func onShow(message: Showable) + + /// Invoked when a message is dismissed + /// - Parameters: + /// - message: UIMessaging message that is being dismissed + @objc(onDismiss:) + func onDismiss(message: Showable) + + /// Used to find whether messages should be shown or not + /// + /// IMPORTANT! - this 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. + /// + /// - Parameters: + /// - message: UIMessaging message that is about to get displayed + /// - Returns: true if the message should be shown else false + @objc(shouldShowMessage:) + func shouldShowMessage(message: Showable) -> Bool + + /// Called when `message` loads a URL + /// - Parameters: + /// - url: the `URL` being loaded by the `message` + /// - message: the Message loading a `URL` + @objc(urlLoaded:byMessage:) + optional func urlLoaded(_ url: URL, byMessage message: Showable) +} +``` + + + +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. + +A reference to the `AEPMessage` object can be obtained by calling `fullscreenMessage.getParent()` . An example of how to access the `Message` in the `onShow` delegate method can be seen below: + +#### Java + +```java +@Override +public void onShow(FullscreenMessage fullscreenMessage) { + Message message = (Message) fullscreenMessage.getParent(); + System.out.println("message was shown: " + message.id); +} +``` + + + +Each of the methods implemented in the `MessagingDelegate` will be passed a [`Showable`](https://github.com/adobe/aepsdk-core-ios/blob/main/AEPServices/Sources/ui/Showable.swift) object. In the AEPMessaging SDK, the class implementing `Showable` is [`FullscreenMessage`](https://github.com/adobe/aepsdk-core-ios/blob/main/AEPServices/Sources/ui/fullscreen/FullscreenMessage.swift). A `FullscreenMessage` object is wrapped in the [`Message`](../public-classes-enums.md) class, and is your primary way to interact with the message. + +To get a reference to the `Message` object: + +1. Convert the `Showable` message parameter to `FullscreenMessage` +2. Access the `parent` variable (note that `parent` is variable defined in `FullscreenMessage+Message.swift`, an extension in the AEPMessaging framework) + +An example of how to access the `Message` in the `onShow` delegate method can be seen below: + +#### Swift + +```swift +func onShow(message: Showable) { + let fullscreenMessage = message as? FullscreenMessage + let message = fullscreenMessage?.parent + print("message was shown \(message?.id ?? "undefined")") +} +``` + + + +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. + +An example of when you may choose to suppress an in-app message due to the status of some other workflow within the app can be seen below: + +#### Java + +```java +@Override +public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { + if (someOtherWorkflowStatus == "inProgress") { + return false; + } + return true; +} +``` + +Another option is to store a reference to the `FullscreenMessage` object, and call the `show()` method on it at a later time. + +Continuing with the above example, after you have stored the message that was triggered initially, you can choose to show it upon completion of the other workflow: + +```java +Message currentMessage = null; +String anotherWorkflowStatus; + +public void otherWorkflowFinished() { + anotherWorkflowStatus = "complete"; + currentMessage.show(); +} + +@Override +public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { + if (someOtherWorkflowStatus.equals("inProgress")) { + // store the current message for later use + currentMessage = (Message) fullscreenMessage.getParent(); + return false; + } + + return true; +} +``` + + + +If a `MessagingDelegate` has been provided to `MobileCore`, the 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. + +An example of when you may choose to suppress an in-app message due to the status of some other workflow within the app can be seen below: + +#### Swift + +```swift +func shouldShowMessage(message: Showable) -> Bool { + if someOtherWorkflowStatus == "inProgress" { + return false + } + + return true +} +``` + +Another option is to store a reference to the `Message` object, and call the `show()` method on it at a later time. + +Continuing with the above example, after you have stored the message that was triggered initially, you can choose to show it upon completion of the other workflow: + +```swift +var currentMessage: Message? + +func otherWorkflowFinished() { + anotherWorkflowStatus = "complete" + currentMessage?.show() +} + +func shouldShowMessage(message: Showable) -> Bool { + if someOtherWorkflowStatus == "inProgress" { + let fullscreenMessage = message as? FullscreenMessage + + // store the current message for later use + currentMessage = fullscreenMessage?.parent + + 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 `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 new file mode 100644 index 0000000000..0e1f2f5b9d --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/tutorials/tabs/native-from-javascript.md @@ -0,0 +1,52 @@ + + +In the `shouldShowMessage` function of the `MessagingDelegate`, call `public void handleJavascriptMessage(final String name, final AdobeCallback callback)` 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 a `decisioning.propositionInteract` Experience Event natively when the JavaScript of the in-app message posts a `myInappCallback` message: + +#### Java + +```java +@Override +public boolean shouldShowMessage(FullscreenMessage fullscreenMessage) { + Message message = (Message) fullscreenMessage.getParent(); + + // in-line handling of JavaScript calls + message.handleJavascriptMessage("myInappCallback", new AdobeCallback() { + @Override + public void call(String content) { + System.out.println("JavaScript body passed to native callback: " + content); + message.track(content, MessagingEdgeEventType.IN_APP_INTERACT); + } + }); +} +``` + + + +In the `shouldShowMessage` function of the `MessagingDelegate`, call [`handleJavascriptMessage(_:withHandler)`](./class-message.md#handlejavascriptmessage_withhandler) 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 a `decisioning.propositionInteract` Experience Event natively when the JavaScript of the in-app message posts a `myInappCallback` message: + +#### Swift + +```swift +func shouldShowMessage(message: Showable) -> Bool { + let fullscreenMessage = message as? FullscreenMessage + let message = fullscreenMessage?.parent + + // in-line handling of JavaScript calls + message?.handleJavascriptMessage("myInappCallback") { content + + print("JavaScript body passed to native callback: \(content ?? "empty")") + + message?.track(content as? String, withEdgeEventType: .inappInteract) + } + + return true +} +``` diff --git a/src/pages/edge/adobe-journey-optimizer/in-app-message/validate-messages.md b/src/pages/edge/adobe-journey-optimizer/in-app-message/validate-messages.md new file mode 100644 index 0000000000..f5eb3fb2b1 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/in-app-message/validate-messages.md @@ -0,0 +1,151 @@ +--- +title: Validate in-app messaging using Adobe Experience Platform Assurance +description: A guide explaining how to validate in-app messaging for Adobe Journey Optimizer using Adobe Experience Platform Assurance. +keywords: +- Adobe Experience Platform Assurance +- Adobe Journey Optimizer +- Guide +- Messaging +- Tutorial +- Validation +--- + +# Validate in-app messaging using Adobe Experience Platform Assurance + +This guide will walk you through steps necessary to ensure your app is properly configured for in-app messaging with Adobe Journey Optimizer (AJO). + +* [Complete prerequisites for your app](#prerequisites) +* [Validate the correct extensions are registered](#validate-the-correct-extensions-are-registered) +* [Validate the event requesting message definitions](#validate-the-event-requesting-message-definitions) +* [Validate the event containing a message definition response](#validate-the-event-containing-a-message-definition-response) + +## Prerequisites + +* Your app must have the **AEPMessaging** SDK extension installed. Integrate **AEPMessaging** by following the guide on [setting up AEPMessaging SDK](../setup.md). + +* This troubleshooting guide uses validation provided by the **AEPAssurance** extension and the **Adobe Assurance UI**. Integrate **AEPAssurance** in your application by following the [Adobe Experience Platform Assurance installation guide](https://experienceleague.adobe.com/docs/experience-platform/assurance/home.html). + +## Validate the correct extensions are registered + +Ensure that your app has registered all necessary AEP SDK extensions by doing the following: + +1. Launch your application with an **AEPAssurance** session active + +2. In the Assurance UI, click on **Shared States** in the left-rail navigation + +3. Click the **+** button next to the row with a **State Path** of **com.adobe.module.eventhub** + +4. Open the **extensions** object and validate that each of the required extensions exist, ensuring it meets the minimum version requirements. The table below shows the minimum versions required for in-app messaging dependencies: + +| Extension (iOS) | Min. Version (iOS) | Extension (Android) | Min. Version (Android) | +| --------------- | -----------------: | ------------------- | ---------------------: | +| AEPCore | 3.7.4 | core | 2.0.1 | +| AEPEdge | 1.1.0 | edge | 2.0.0 | +| AEPEdgeIdentity | 1.0.0 | edgeidentity | 2.0.0 | +| AEPMessaging | 1.1.0 | messaging | 2.0.0 | + + + +If your app uses the [Edge Consent extension](../../consent-for-edge-network/index.md), the device must be consenting (i.e. - a consent value of `Yes`) in order to download in-app messages. + +A sample view in the Assurance UI can be seen below: + +![correct extensions registered](./assets/validate-messages/message-configuration.png) + +## Validate the event requesting message definitions + +When the AEPMessaging extension has finished registration with the AEP SDK and a valid configuration exists, it will automatically initiate a network request to fetch message definitions from the remote. + +Completing the following steps will validate that your app is making the necessary request to retrieve in-app message definitions: + +1. Launch your application with an **AEPAssurance** session active + +2. In the Assurance UI, click on **Events** in the left-rail navigation + +3. In the event list, select the event with type **Retrieve message definitions** + +![Retrieve message definitions](./assets/validate-messages/message-request.png) + +4. Expand the **Payload** section in the right window and ensure the correct **surface** is being used. The **surface** URI represents a collection of messages specific for your application and is identifiable based on its bundle identifier. The format for the URI will be `mobileapp://APP_BUNDLE_IDENTIFIER`. From the screenshot above, the surface in use is `mobileapp://com.adobe.MessagingDemoApp`. + +## Validate the event containing a message definition response + +After the request from the previous step returns, the **AEPEdge** extension will dispatch a response event containing data returned by the remote server. + +Complete the following steps to validate a response containing in-app messages: + +1. Launch your application with an **AEPAssurance** session active + +2. In the Assurance UI, click on **Events** in the left-rail navigation + +3. In the event list, select the event with type **AEP Response Event Handle**. There will likely be several events with this type - ensure the one selected has an **AEPExtensionEventSource** of `personalization:decisions` + +![AEP Response Event Handle](./assets/validate-messages/message-response.png) + +4. Expand the **Payload** section in the right window. Each entry in the **payload** array contains the rule for a single in-app message that has been previously published in AJO and is now live. The full path to find a message definition is: + + ```shell + ACPExtensionEventData.payload.N.items.0.data.content + ``` + + To find definitions for other live in-app messages, follow the above path for each object in the **payload** array. + + ![AEP Response Event Handle Payload](./assets/validate-messages/message-response-payload.png) + +## Use the In-App Messaging Assurance UI plugin + +Once all of the above validation sections are complete, you can use the **In-App Messaging** plugin view in the Assurance UI to further debug your app. + +#### Install the In-App Messaging plugin + + + +If you have already installed the **In-App Messaging** plugin in your Assurance UI setup, skip this section. + +1. In the Assurance UI, click on **Configure** button at the bottom of the left-rail navigation + +2. Search for the row named **In-App Messaging** under the **ADOBE JOURNEY OPTIMIZER (BETA)** heading, and click the **+** button on its right + +3. Click the **Save** button + +![Install the In-App Messaging plugin](./assets/validate-messages/install-iam-plugin.png) + +#### Inspecting a downloaded message + +Using the IAM plugin you can do the following for each message downloaded by the client: + +* In the **Rules** tab - view the rules defining when the message will be shown to the user +* In the **History** tab - review a history of client events, including a comparison between the event's contents and the message's triggering criteria +* In the **Message Preview** window - see a preview of the message's html +* In the **Message Behavior** window - review message behavior, including its supported gestures and animations +* In the **Message Behavior** window - review message size and positioning properties +* Clicking the **Simulate on Device** button - trigger the currently selected message, causing it to be displayed on the connected client + + ![Inspecting a downloaded message](./assets/validate-messages/iam-simulation.png) + +## FAQs + +### Q: What do I do when one of the required extensions is missing? + +**A:** Ensure that each required extension is linked to your project and registered by `MobileCore`. For more information, please read the [Mobile Core API reference](../../mobile-core/api-reference.md#registerextensions). + +### Q: Why can't I find an event named `Retrieve message definitions`? + +**A:** Ensure that each of the required extensions is at the minimum required version. + +### Q: I see an `AEP Error Response` event, is that a problem? + +**A:** If you open the EventData and the `detail` key has a value of "The Decisioning Package was not found.", this likely means the Messaging extension was unable to find the messages for your app. Check the below items to try and resolve the issue: + +* Make sure that messages have been published in the AJO Campaigns UI for your app surface +* Make sure that the bundle identifier (iOS) or package name (Android) matches the value used for your app surface +* Make sure that the **environment** and **sandbox** being used in AJO matches those being used to configure the app +* Make sure that your Adobe organization is provisioned for Offers on Edge (this may require contacting your account manager) + +### Q: Why don't I see any messages in my `AEP Response Event Handle` event? + +**A:** In the [Adobe Journey Optimizer UI](https://experience.adobe.com/#/@/journey-optimizer/home), make sure that there are in-app messages with a **Live** status for your application. + +### Q: Why aren't there any messages to select in the `In-App Messaging` Assurance UI plugin? + +**A:** The `In-App Messaging` plugin view will only be populated when there are messages returned in the `AEP Response Event Handle` event. diff --git a/src/pages/edge/adobe-journey-optimizer/index.md b/src/pages/edge/adobe-journey-optimizer/index.md index a9af4fa80a..1a713561d4 100644 --- a/src/pages/edge/adobe-journey-optimizer/index.md +++ b/src/pages/edge/adobe-journey-optimizer/index.md @@ -87,20 +87,6 @@ iOS -#### Sync the user push token with Adobe - -If your app will be using AJO powered push notifications, you will need to sync the push token with Adobe Experience Platform by using the `MobileCore.setPushIdentifier` API. - - - -Android - - - -iOS - - - ## Configuration keys You can update the SDK configuration, including the Messaging configuration values, programmatically by using the following information. @@ -110,18 +96,7 @@ You can update the SDK configuration, including the Messaging configuration valu | messaging.eventDataset | Yes | Experience Event Dataset ID which can be found from Experience Platform | String | Android/iOS | | messaging.useSandbox | No | A variable that lets the `apnsSandbox` environment be used for receiving push notifications. More details can be found in the [messaging documentation](https://github.com/adobe/aepsdk-messaging-ios/blob/main/Documentation/sources/getting-started.md#using-an-apns-sandbox-push-environment) | Boolean | iOS | -## Guides and How-tos - -* [Track Push Interactions](api-reference.md#addpushtrackingdetails) -* [Programmatically control the display of in-app messages](./tutorials/messaging-delegate.md) -* [Call native code from the JavaScript of an in-app message](./tutorials/native-from-javascript.md) -* [Execute JavaScript code in an in-app message from native code](./tutorials/javascript-from-native.md) -* [Handle URL clicks from an in-app message](./tutorials/handle-clicks.md) - -### Other public classes, methods, and enums - -* [Public classes and enums](./public-classes.md) - -### Troubleshooting +## Next Steps -* [Validate in-app messaging using AEPAssurance SDK extension and the Assurance UI](./tutorials/validate-messages.md) +* [Push notification implementation guide](./push-notification/index.md) +* [In-App message implementation guide](./in-app-message/index.md) diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/index.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/index.md new file mode 100644 index 0000000000..aa29cbd9dd --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/index.md @@ -0,0 +1,26 @@ +--- +title: Public Classes and Enums +description: This documents lists all details about the public classes and enums available in Messaging extension. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- Public Classes +- Enum +- Enumeration +- In-App Message +--- + +# Public Classes and Enums + +This documents lists all details about the public classes and enums available in Messaging extension. + +## Push Notification + +* [Class - MessagingPushPayload](./messaging-push-payload.md) +* [Enum - PushTrackingStatus](./push-tracking-status.md) + +## In-App Message + +* [Class - Message](./message.md) +* [Enum - MessagingEdgeEventType](./messaging-edge-event-type.md) diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/message.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/message.md new file mode 100644 index 0000000000..c354ef154d --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/message.md @@ -0,0 +1,190 @@ +--- +title: +description: <description> +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- iOS +--- +import Tabs from './tabs/message.md' + +# Message + +The `Message` class contains the definition of an in-app message and controls its tracking via Experience Edge events. + +## iOS Interface - Message + +`Message` objects are only created by the AEPMessaging extension, and passed as the `message` parameter in `MessagingDelegate` protocol methods. + +## Public variables + +### id + +Identifier of the `Message`. This value matches the Message Execution ID assigned by Adobe Journey Optimizer (AJO) Campaign. + +```swift +public var id: String +``` + +### autoTrack + +If set to `true` (default), Experience Edge events will automatically be generated when this `Message` is triggered, displayed, and dismissed. + +```swift +public var autoTrack: Bool = true +``` + +### view + +Holds a reference to the message's `WKWebView` (iOS) or `WebView` (Android) instance, if it exists. + +```swift +public var view: UIView? { + fullscreenMessage?.webView +} +``` + +## Public functions + +### show + +Signals to the UIService (in `AEPServices`) that the message should be shown. + +If `autoTrack` is true, calling this method will result in an `decisioning.propositionTrigger` Edge Event being dispatched. + +```swift +public func show() +``` + +### dismiss(suppressAutoTrack:) + +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. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="0"/> + +iOS + +<Tabs query="platform=ios&function=dismiss"/> + +### track(_:withEdgeEventType:) + +Generates and dispatches an Edge Event for the provided `interaction` and `eventType`. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=track"/> + +### handleJavascriptMessage(_:withHandler:) + +Adds a handler for named JavaScript messages sent from the message's `WKWebView`. + +The parameter passed to `handler` will contain the body of the message passed from the `WKWebView`'s JavaScript. + +For a full guide on how to use `handleJavascriptMessage`, read [Call native code from the Javascript of an in-app message](./tutorials/native-from-javascript.md). + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=handle-javascript-message"/> + +## Android Interface - Message + +`InternalMessage` objects implementing this interface are created by the AEPMessaging extension, and passed as the `message` parameter in `MessagingDelegate` interface methods. + +## Public functions + +### show + +Signals to the UIService that the message should be shown. + +If `autoTrack` is true, calling this method will result in an "decisioning.propositionDisplay" Edge Event being dispatched. + +```java +void show() +``` + +### dismiss + +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. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=dismiss"/> + +### track + +Generates and dispatches an Edge Event for the provided `interaction` and `eventType`. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=track"/> + +### setAutoTrack + +Sets the `Message's` auto tracking preference. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=auto-track"/> + +### evaluateJavascript + +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` . + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=evaluate-javascript"/> + +### handleJavascriptMessage + +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 [Call native code from the Javascript of an in-app message](./how-to-call-native-from-javascript.md). + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=handle-javascript-message"/> + +### getId + +Returns the message's id. + +```java +String getId() +``` + +### getParent + +Returns the `Object` which created this `Message`. + +```java +Object getParent() +``` + +### getWebView + +Returns a reference to the message's `WebView` instance, if it exists. + +```java +WebView getWebView() +``` diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-edge-event-type.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-edge-event-type.md new file mode 100644 index 0000000000..c9028bc8ac --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-edge-event-type.md @@ -0,0 +1,37 @@ +--- +noIndex: true +--- + +import Tabs from './tabs/messaging-edge-event-type.md' + +# Enum - MessagingEdgeEventType + +Provides mapping to XDM EventType strings needed for Experience Event requests. + +This enum is used in conjunction with the [`track(_:withEdgeEventType:)`](./message.md#track_withedgeeventtype) method of a `Message` object. + +## Definition + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=enum"/> + +iOS + +<Tabs query="platform=ios&function=enum"/> + +## String values + +Below is the table of values returned by calling the `toString` method for each case, which are used as the XDM `eventType` in outgoing experience events: + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=string-values"/> + +iOS + +<Tabs query="platform=ios&function=string-values"/> diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-push-payload.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-push-payload.md new file mode 100644 index 0000000000..ad3f9170e7 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/messaging-push-payload.md @@ -0,0 +1,121 @@ +--- +title: MessagingPushPayload +description: This document explains how to use MessagingPushPayload class for getting the notification attributes like title, body, actions etc for creating a push notification from a received AJO push payload. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- Android +- MessagingPushPayload +- Manual Display and Tracking +--- + +# MessagingPushPayload + +This document explains how to use MessagingPushPayload class for getting the notification attributes like title, body, actions etc for creating a push notification received from Adobe Journey Optimizer (AJO). + +MessagePushPayload is an Android only helper class for extracting the data payload attributes from RemoteMessage. Use this class for [manual display and tracking of push notifications](../push-notification/android/manual-display-and-tracking.md). + +## Creating the MessagingPushPayload object + +Use the below constructors in the FirebaseMessagingService class's onMessageReceived method: + +#### Syntax + +```java + // Using the remote message + public MessagingPushPayload(RemoteMessage message) + + // Using the data map + public MessagingPushPayload(Map<String, String> data) +``` + +#### Example + +```java +// Using the remote message +@Override +public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { + MessagingPushPayload payload = new MessagingPushPayload(remoteMessage); +} + +// Using the data map +@Override +public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { + MessagingPushPayload payload = new MessagingPushPayload(remoteMessage.getData()); +} +``` + +## Public API's + +Public APIs are used to get attributes from the push payload, which are used while creating the push notification. + +```java +// Returns the title from the remote message +public String getTitle() + +// Returns the body from the remote message +public String getBody() + +// Returns the sound from the remote message +// The sound string represents the filename of a sound resource bundled in the app. +public String getSound() + +// Returns the notification badge count from the remote message +public int getBadgeCount() + +// Returns the notification priority from the remote message. +// For more information, please read the Firebase documentation (https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notificationpriority) +public int getNotificationPriority() + +// Returns the channel ID from the remote message. +public String getChannelId() + +// Returns the icon string from the remote message. +// The icon string represents the drawable resource name in the app. +public String getIcon() + +// Returns the image URL from the remote message. +public String getImageUrl() + +// Returns the data map from the remote message. +public Map<String, String> getData() + +// Returns an ActionType object which represents the type of action which needs to be performed on push notification interaction. +// More information about the ActionType enum definition can be found in the ActionType section below. +public ActionType getActionType() + +// Returns the action URI as a string. The action URI is used to direct the push notification interaction. +public String getActionUri() + +// Returns a list of ActionButtons. More information about the ActionButtons class definition can be found in the ActionButtons section below. +public List<ActionButton> getActionButtons() +``` + +### Internal classes and enums + +**ActionType** + +```java +public enum ActionType { + DEEPLINK, WEBURL, OPENAPP, NONE +} +``` + +**ActionButtons** + +```java +// Constructor +public ActionButton(final String label, final String link, final String type) + +// Public APIs + +// Returns the label for the action button +public String getLabel() + +// Returns the link for the action button +public String getLink() + +// Returns the ActionType for the action button +public ActionType getType() +``` diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/public-classes.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/public-classes.md new file mode 100644 index 0000000000..a553f7be2b --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/public-classes.md @@ -0,0 +1,237 @@ +--- +title: Adobe Journey Optimizer public class reference +description: A public class reference for the Adobe Journey Optimizer (AJO) mobile extension. +keywords: +- Adobe Journey Optimizer +- API reference +- Messaging +- Public class +--- + +import Tabs from './tabs/public-classes.md' + +# iOS Class - Message + +The `Message` class contains the definition of an in-app message and controls its tracking via Experience Edge events. + +`Message` objects are only created by the AEPMessaging extension, and passed as the `message` parameter in `MessagingDelegate` protocol methods. + +## Public variables + +### id + +Identifier of the `Message`. This value matches the Message Execution ID assigned by Adobe Journey Optimizer (AJO) Campaign. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=id"/> + +### autoTrack + +If set to `true` (default), Experience Edge events will automatically be generated when this `Message` is triggered, displayed, and dismissed. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=auto-track"/> + +### view + +Holds a reference to the message's `WKWebView` (iOS) or `WebView` (Android) instance, if it exists. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=view"/> + +## Public functions + +### show + +Signals to the UIService (in `AEPServices`) that the message should be shown. + +If `autoTrack` is true, calling this method will result in an `decisioning.propositionTrigger` Edge Event being dispatched. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=show"/> + +### dismiss(suppressAutoTrack:) + +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. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=dismiss"/> + +### track(_:withEdgeEventType:) + +Generates and dispatches an Edge Event for the provided `interaction` and `eventType`. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=track"/> + +### handleJavascriptMessage(_:withHandler:) + +Adds a handler for named JavaScript messages sent from the message's `WKWebView`. + +The parameter passed to `handler` will contain the body of the message passed from the `WKWebView`'s JavaScript. + +For a full guide on how to use `handleJavascriptMessage`, read [Call native code from the Javascript of an in-app message](./tutorials/native-from-javascript.md). + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +iOS + +<Tabs query="platform=ios&function=handle-javascript-message"/> + +## Android Interface - Message + +The `Message` interface contains the definition of an in-app message and provides a framework to track message interactions via Experience Edge events. + +`InternalMessage` objects implementing this interface are created by the AEPMessaging extension, and passed as the `message` parameter in `MessagingDelegate` interface methods. + +## Public functions + +### show + +Signals to the UIService that the message should be shown. + +If `autoTrack` is true, calling this method will result in an "decisioning.propositionDisplay" Edge Event being dispatched. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=show"/> + +### dismiss + +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. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=dismiss"/> + +### track + +Generates and dispatches an Edge Event for the provided `interaction` and `eventType`. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=track"/> + +### setAutoTrack + +Sets the `Message's` auto tracking preference. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=auto-track"/> + +### evaluateJavascript + +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` . + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=evaluate-javascript"/> + +### handleJavascriptMessage + +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 [Call native code from the Javascript of an in-app message](./how-to-call-native-from-javascript.md). + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=handle-javascript-message"/> + +### getId + +Returns the message's id. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=id"/> + +### getParent + +Returns the `Object` which created this `Message`. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=parent"/> + +### getWebView + +Returns a reference to the message's `WebView` instance, if it exists. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="1"/> + +Android + +<Tabs query="platform=android&function=view"/> + +# Enum - MessagingEdgeEventType + +Provides mapping to XDM EventType strings needed for Experience Event requests. + +This enum is used in conjunction with the [`track(_:withEdgeEventType:)`](#track_withedgeeventtype) method of a `Message` object. + +### Definition + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=enum"/> + +iOS + +<Tabs query="platform=ios&function=enum"/> + +### String values + +Below is the table of values returned by calling the `toString` method for each case, which are used as the XDM `eventType` in outgoing experience events: + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=string-values"/> + +iOS + +<Tabs query="platform=ios&function=string-values"/> diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/push-tracking-status.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/push-tracking-status.md new file mode 100644 index 0000000000..7d1e90e20f --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/push-tracking-status.md @@ -0,0 +1,41 @@ +--- +title: PushTrackingStatus +description: Enum representing the status of push tracking. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- iOS +- Android +- PushTrackingStatus +--- + +import Tabs from './tabs/push-tracking-status.md' + +# Enum - PushTrackingStatus + +Enum representing the status of push tracking. + +## Definition + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=enum"/> + +iOS + +<Tabs query="platform=ios&function=enum"/> + +## Description + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&function=string-values"/> + +iOS + +<Tabs query="platform=ios&function=string-values"/> diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/message.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/message.md new file mode 100644 index 0000000000..4328cad614 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/message.md @@ -0,0 +1,101 @@ +--- +noIndex: true +--- + +<Variant platform="ios" function="dismiss" repeat="3"/> + +```swift +public func dismiss(suppressAutoTrack: Bool? = false) +``` + +###### Parameters + +* *suppressAutoTrack* - if set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. + +<Variant platform="ios" function="track" repeat="4"/> + +#### Swift + +```swift +public func track(_ interaction: String?, withEdgeEventType eventType: MessagingEdgeEventType) +``` + +###### 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 + +<Variant platform="ios" function="handle-javascript-message" repeat="4"/> + +#### Swift + +```swift +public func handleJavascriptMessage(_ name: String, withHandler handler: @escaping (Any?) -> Void) +``` + +##### Parameters + +* *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 + +<Variant platform="android" function="dismiss" repeat="4"/> + +#### Java + +```java +void dismiss(final boolean suppressAutoTrack) +``` + +##### Parameters + +* *suppressAutoTrack* - if set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. + +<Variant platform="android" function="track" repeat="4"/> + +#### Java + +```java +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 + +<Variant platform="android" function="handle-javascript-message" repeat="4"/> + +#### Java + +```java +void handleJavascriptMessage(final String name, final AdobeCallback<String> callback) +``` + +##### Parameters + +* *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 + +<Variant platform="android" function="auto-track" repeat="4"/> + +#### Java + +```java +void setAutoTrack(boolean enabled) +``` + +##### Parameters + +* *enabled* - if true, Experience Edge events will automatically be generated when this `Message` is triggered, displayed, or dismissed. + +<Variant platform="android" function="evaluate-javascript" repeat="4"/> + +#### Java + +```java +void evaluateJavascript(final String content) +``` + +##### Parameters + +* *content* - a string containing the javascript code to be executed diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/messaging-edge-event-type.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/messaging-edge-event-type.md new file mode 100644 index 0000000000..a867202e1f --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/messaging-edge-event-type.md @@ -0,0 +1,102 @@ +--- +noIndex: true +--- + +<Variant platform="android" function="enum" repeat="2"/> + +#### 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; + + MessagingEdgeEventType(final int value) { + this.value = value; + } + + public int getValue() { + return value; + } + + @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 PUSH_APPLICATION_OPENED: + return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.OPENED; + case PUSH_CUSTOM_ACTION: + return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.CUSTOM_ACTION; + default: + return super.toString(); + } + } +``` + +<Variant platform="ios" function="enum" repeat="2"/> + +#### Swift + +```swift +@objc(AEPMessagingEdgeEventType) +public enum MessagingEdgeEventType: Int { + case inappDismiss = 0 + case inappInteract = 1 + case inappTrigger = 2 + case inappDisplay = 3 + case pushApplicationOpened = 4 + case pushCustomAction = 5 + + public func toString() -> String { + switch self { + case .inappDismiss: + return MessagingConstants.XDM.IAM.EventType.DISMISS + case .inappTrigger: + return MessagingConstants.XDM.IAM.EventType.TRIGGER + case .inappInteract: + return MessagingConstants.XDM.IAM.EventType.INTERACT + case .inappDisplay: + return MessagingConstants.XDM.IAM.EventType.DISPLAY + case .pushCustomAction: + return MessagingConstants.XDM.Push.EventType.CUSTOM_ACTION + case .pushApplicationOpened: + return MessagingConstants.XDM.Push.EventType.APPLICATION_OPENED + } + } +} +``` + +<Variant platform="android" function="string-values" repeat="1"/> + +| Case | String value | +| ---- | ------------ | +| IN_APP_DISMISS | `decisioning.propositionDismiss` | +| IN_APP_INTERACT | `decisioning.propositionInteract` | +| IN_APP_TRIGGER | `decisioning.propositionTrigger` | +| IN_APP_DISPLAY | `decisioning.propositionDisplay` | +| PUSH_APPLICATION_OPENED | `pushTracking.applicationOpened` | +| PUSH_CUSTOM_ACTION | `pushTracking.customAction` | + +<Variant platform="ios" function="string-values" repeat="1"/> + +| Case | String value | +| ---- | ------------ | +| inappDismiss | `decisioning.propositionDismiss` | +| inappInteract | `decisioning.propositionInteract` | +| inappTrigger | `decisioning.propositionTrigger` | +| inappDisplay | `decisioning.propositionDisplay` | +| pushApplicationOpened | `pushTracking.applicationOpened` | +| pushCustomAction | `pushTracking.customAction` | diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/public-classes.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/public-classes.md new file mode 100644 index 0000000000..520ff7f173 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/public-classes.md @@ -0,0 +1,268 @@ +--- +noIndex: true +--- + +<Variant platform="ios" function="id" repeat="2"/> + +#### Swift + +```swift +public var id: String +``` + +<Variant platform="ios" function="auto-track" repeat="2"/> + +#### Swift + +```swift +public var autoTrack: Bool = true +``` + +<Variant platform="ios" function="view" repeat="2"/> + +#### Swift + +```swift +public var view: UIView? { + fullscreenMessage?.webView +} +``` + +<Variant platform="ios" function="show" repeat="2"/> + +#### Swift + +```swift +public func show() +``` + +<Variant platform="ios" function="dismiss" repeat="4"/> + +#### Swift + +```swift +public func dismiss(suppressAutoTrack: Bool? = false) +``` + +###### Parameters + +* *suppressAutoTrack* - if set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. + +<Variant platform="ios" function="track" repeat="4"/> + +#### Swift + +```swift +public func track(_ interaction: String?, withEdgeEventType eventType: MessagingEdgeEventType) +``` + +###### 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 + +<Variant platform="ios" function="handle-javascript-message" repeat="4"/> + +#### Swift + +```swift +public func handleJavascriptMessage(_ name: String, withHandler handler: @escaping (Any?) -> Void) +``` + +##### Parameters + +* *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 + +<Variant platform="android" function="dismiss" repeat="4"/> + +#### Java + +```java +void dismiss(final boolean suppressAutoTrack) +``` + +##### Parameters + +* *suppressAutoTrack* - if set to `true`, the `decisioning.propositionDismiss` Edge Event will not be sent regardless of the `autoTrack` setting. + +<Variant platform="android" function="track" repeat="4"/> + +#### Java + +```java +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 + +<Variant platform="android" function="show" repeat="2"/> + +#### Java + +```java +void show() +``` + +<Variant platform="android" function="view" repeat="2"/> + +#### Java + +```java +WebView getWebView() +``` + +<Variant platform="android" function="handle-javascript-message" repeat="4"/> + +#### Java + +```java +void handleJavascriptMessage(final String name, final AdobeCallback<String> callback) +``` + +##### Parameters + +* *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 + +<Variant platform="android" function="auto-track" repeat="4"/> + +#### Java + +```java +void setAutoTrack(boolean enabled) +``` + +##### Parameters + +* *enabled* - if true, Experience Edge events will automatically be generated when this `Message` is triggered, displayed, or dismissed. + +<Variant platform="android" function="evaluate-javascript" repeat="4"/> + +#### Java + +```java +void evaluateJavascript(final String content) +``` + +##### Parameters + +* *content* - a string containing the javascript code to be executed + +<Variant platform="android" function="id" repeat="2"/> + +#### Java + +```java +String getId() +``` + +<Variant platform="android" function="parent" repeat="2"/> + +#### Java + +```java +Object getParent() +``` + +<Variant platform="android" function="enum" repeat="2"/> + +#### 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; + + MessagingEdgeEventType(final int value) { + this.value = value; + } + + public int getValue() { + return value; + } + + @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 PUSH_APPLICATION_OPENED: + return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.OPENED; + case PUSH_CUSTOM_ACTION: + return MessagingConstants.EventDataKeys.Messaging.PushNotificationDetailsDataKeys.EventType.CUSTOM_ACTION; + default: + return super.toString(); + } + } +``` + +<Variant platform="ios" function="enum" repeat="2"/> + +#### Swift + +```swift +@objc(AEPMessagingEdgeEventType) +public enum MessagingEdgeEventType: Int { + case inappDismiss = 0 + case inappInteract = 1 + case inappTrigger = 2 + case inappDisplay = 3 + case pushApplicationOpened = 4 + case pushCustomAction = 5 + + public func toString() -> String { + switch self { + case .inappDismiss: + return MessagingConstants.XDM.IAM.EventType.DISMISS + case .inappTrigger: + return MessagingConstants.XDM.IAM.EventType.TRIGGER + case .inappInteract: + return MessagingConstants.XDM.IAM.EventType.INTERACT + case .inappDisplay: + return MessagingConstants.XDM.IAM.EventType.DISPLAY + case .pushCustomAction: + return MessagingConstants.XDM.Push.EventType.CUSTOM_ACTION + case .pushApplicationOpened: + return MessagingConstants.XDM.Push.EventType.APPLICATION_OPENED + } + } +} +``` + +<Variant platform="android" function="string-values" repeat="1"/> + +| Case | String value | +| ---- | ------------ | +| IN_APP_DISMISS | `decisioning.propositionDismiss` | +| IN_APP_INTERACT | `decisioning.propositionInteract` | +| IN_APP_TRIGGER | `decisioning.propositionTrigger` | +| IN_APP_DISPLAY | `decisioning.propositionDisplay` | +| PUSH_APPLICATION_OPENED | `pushTracking.applicationOpened` | +| PUSH_CUSTOM_ACTION | `pushTracking.customAction` | + +<Variant platform="ios" function="string-values" repeat="1"/> + +| Case | String value | +| ---- | ------------ | +| inappDismiss | `decisioning.propositionDismiss` | +| inappInteract | `decisioning.propositionInteract` | +| inappTrigger | `decisioning.propositionTrigger` | +| inappDisplay | `decisioning.propositionDisplay` | +| pushApplicationOpened | `pushTracking.applicationOpened` | +| pushCustomAction | `pushTracking.customAction` | diff --git a/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/push-tracking-status.md b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/push-tracking-status.md new file mode 100644 index 0000000000..04d5f018db --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/public-classes-and-enum/tabs/push-tracking-status.md @@ -0,0 +1,50 @@ +--- +noIndex: true +--- + +<Variant platform="android" function="enum" repeat="1"/> + +```java +public enum PushTrackingStatus { + TRACKING_INITIATED, + NO_DATASET_CONFIGURED, + NO_TRACKING_DATA, + INVALID_INTENT, + INVALID_MESSAGE_ID, + UNKNOWN_ERROR; +} +``` + +<Variant platform="ios" function="enum" repeat="1"/> + +```swift +@objc(AEPPushTrackingStatus) +public enum PushTrackingStatus: Int { + case trackingInitiated + case noDatasetConfigured + case noTrackingData + case invalidMessageId + case unknownError +} +``` + +<Variant platform="android" function="string-values" repeat="1"/> + +| Enum | Description | +| ----------------------- | --------------------------------- | +| TRACKING_INITIATED | This status is returned when all the required data for tracking is available and tracking is initiated. | +| NO_DATASET_CONFIGURED | This status is returned when tracking is not initiated because no tracking dataset is configured. | +| NO_TRACKING_DATA | This status is returned when tracking is not initiated because the intent does not contain tracking data.| +| INVALID_INTENT | This status is returned when tracking is not initiated because the intent is invalid. | +| INVALID_MESSAGE_ID | This status is returned when tracking is not initiated because the message id is invalid. | +| UNKNOWN_ERROR | This status is returned when tracking is not initiated because of an unknown error. | + +<Variant platform="ios" function="string-values" repeat="1"/> + +| Enum | Description | +| ----------------------- | --------------------------------- | +| trackingInitiated | This status is returned when all the required data for tracking is available and tracking is initiated. | +| noDatasetConfigured | This status is returned when tracking is not initiated because no tracking dataset is configured. | +| noTrackingData | This status is returned when tracking is not initiated because the intent does not contain tracking data.| +| invalidMessageId | This status is returned when tracking is not initiated because the message id is invalid. | +| unknownError | This status is returned when tracking is not initiated because of an unknown error. | diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/android/automatic-display-and-tracking.md b/src/pages/edge/adobe-journey-optimizer/push-notification/android/automatic-display-and-tracking.md new file mode 100644 index 0000000000..a76fbda7f9 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/android/automatic-display-and-tracking.md @@ -0,0 +1,108 @@ +--- +title: Automatically display and track push notification +description: This document describes how to automatically display and track push notifications using the AEPMessaging extension. We highly recommend to use this method unless you have a specific requirement to manually display and track push notifications. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- Android +- API +- Auto track +- Display push notification +- auto track push notification +--- + +# Automatically display and track push notification + +This document describes how to automatically display and track push notifications using the AEPMessaging extension. We highly recommend to use this method unless you have a specific requirement to manually display and track push notifications. + +## Pre-requisites + +[Integrate and register Messaging extension](../../../index.md#implement-extension-in-mobile-app) in your app. + +## Sync the push token + +To retrieve the push token from Firebase Messaging Service, please follow the tutorial within the [Firebase documentation](https://firebase.google.com/docs/cloud-messaging/android/client#retrieve-the-current-registration-token). Then use `setPushIdentifier` API to sync the device's push token with profile in Adobe Experience Platform. + +<InlineAlert variant="info" slots="text"/> + +Although this API is provided in Mobile Core, the use of this API is required and leveraged by the Adobe Journey Optimizer extension to sync provided push tokens with Adobe Experience Platform services. + +```java +public class YourApp extends Application { + + @Override + public void onCreate() { + super.onCreate(); + FirebaseMessaging.getInstance().getToken().addOnCompleteListener(new OnCompleteListener<String>() { + + @Override + public void onComplete(@NonNull Task<String> task) { + if (task.isSuccessful()) { + String token = task.getResult(); + MobileCore.setPushIdentifier(token); + } + } + }); + } +} +``` + +## Display and track push notification + +### Register Messaging extension's FirebaseMessagingService + +<InlineAlert variant="info" slots="text"/> + +If your application already registered a `FirebaseMessagingService` class, then you can skip this step and move to the [Using your own FirebaseMessagingService](#using-your-own-firebasemessagingservice) section. + +Messaging extension uses `MessagingService` to receive, display and track push notifications. To register the `MessagingService` add the following code to the `AndroidManifest.xml` file: + +```java + <service + android:name="com.adobe.marketing.mobile.messaging.MessagingService" + android:exported="false"> + <intent-filter> + <action android:name="com.google.firebase.MESSAGING_EVENT" /> + </intent-filter> + </service> +``` + +### Using your own FirebaseMessagingService + +If your application already registered a `FirebaseMessagingService` class, then you can use the following API to display and track push notifications originated from Adobe Journey Optimizer. + +```java +public class YourAppFirebaseMessagingService extends FirebaseMessagingService { + @Override + public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { + if (MessagingService.handleRemoteMessage(this, message)) { + // Push notification originated from Adobe Journey Optimizer is handled by the Messaging extension. + } else { + // Handle push notification originated from other sources. + } + } +} +``` + +## Notification Channel + +Notification channel was introduced in Android Oreo (API level 26). It allows you to group notifications and allows users to customize the notification preferences for each channel. + +You must create at least one notification channel to display push notifications on devices running Android Oreo or higher. Follow the [android documentation](https://developer.android.com/develop/ui/views/notifications/channels) to create and manage notification channels. Once a notification channel is created, you can use the channel id while [designing the push notification](https://experienceleague.adobe.com/docs/journey-optimizer/using/push/design-push.html) in Adobe Journey Optimizer. + +**Default Channel**: If you do not create a notification channel, or if the notification channel specified while designing the push notification does not match with any of the created channels, the Messaging extension will present the push notification through its predefined fallback notification channel, which is named "General Notifications." + +## Configuring Small Icon + +Use MobileCore's API to set the small icon resource id. This icon will be used as the small icon for all the incoming push notification from Adobe Journey Optimizer. + +```java +MobileCore.setSmallIconResourceId(R.drawable.ic_notification); +``` + +When no custom small icon is specified, the Messaging extension will automatically utilize the application's launcher icon as the default small icon. + +## Notification Actions + +Messaging extension will automatically handle any click behaviour that is configured while [designing the push notification in Adobe Journey Optimizer](https://experienceleague.adobe.com/docs/journey-optimizer/using/push/design-push.html) or Assurance. diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/android/manual-display-and-tracking.md b/src/pages/edge/adobe-journey-optimizer/push-notification/android/manual-display-and-tracking.md new file mode 100644 index 0000000000..aed8baefb2 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/android/manual-display-and-tracking.md @@ -0,0 +1,171 @@ +--- +title: Manual display and tracking of push notification +description: This document describes how to manually build, display and track push notifications from Adobe Journey Optimizer using the AEPMessaging extension. We highly recommend to use the automatic display and tracking method unless you have a specific requirement to manually display and track push notifications. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- Android +- API +--- + +# Manual display and tracking of push notification + +This document describes how to manually build, display and track push notifications from Adobe Journey Optimizer using the AEPMessaging extension. We highly recommend to use the [automatic display and tracking](./automatic-handling-and-tracking.md) method unless you have a specific requirement to manually display and track push notifications. + +## Pre-requisites + +[Integrate and register Messaging extension](../../../index.md#implement-extension-in-mobile-app) in your app. + +## Sync the push token + +To retrieve the push token from Firebase Messaging Service, please follow the tutorial within the [Firebase documentation](https://firebase.google.com/docs/cloud-messaging/android/client#retrieve-the-current-registration-token). Then use `setPushIdentifier` API to sync the device's push token with profile in Adobe Experience Platform. + +<InlineAlert variant="info" slots="text"/> + +Although this API is provided in Mobile Core, the use of this API is required and leveraged by the Adobe Journey Optimizer extension to sync provided push tokens with Adobe Experience Platform services. + +```java +public class YourApp extends Application { + + @Override + public void onCreate() { + super.onCreate(); + FirebaseMessaging.getInstance().getToken().addOnCompleteListener(new OnCompleteListener<String>() { + + @Override + public void onComplete(@NonNull Task<String> task) { + if (task.isSuccessful()) { + String token = task.getResult(); + MobileCore.setPushIdentifier(token); + } + } + }); + } +} +``` + +## Building and displaying notification + +1. In `onMessageReceived` method of `YourAppFirebaseMessagingService` class, create a `MessagingPushPayload` object from the remoteMessage. `MessagingPushPayload` will unpack the remoteMessage and provide APIs for getting attributes used for creating the push notification. + + ```java + MessagingPushPayload payload = new MessagingPushPayload(remoteMessage); + ``` + +2. Use the [Public API's](../enum-public-classes/messaging-push-payload.md) of MessagingPushPayload to get the attributes required for creating the push notification. + + ```java + // Following are a few examples of using the public APIs of MessagingPushPayload + String title = payload.getTitle(); + String body = payload.getBody(); + int badgeCount = payload.getBadgeCount(); + int notificationPriority = payload.getNotificationPriority(); + String channelId = payload.getChannelId(); + String icon = payload.getIcon(); + String imageUrl = payload.getImageUrl(); + ``` + +3. The intent which is created while building the notification needs to be updated with necessary Adobe information to track push notification interactions. + + ```java + Messaging.addPushTrackingDetails( + final Intent intent, // intent which will be used when user interacts with the notification. + final String messageId, // message.id which represents the id of the push notification + final Map<String, String> data) // message.data which represents the data part of the remoteMessage. + ``` + +4. Use NotificationManager to create and display the built notification. + +Here is a sample code for creating a notification channel and building the notification. + +```java +public class YourAppFirebaseMessagingService extends FirebaseMessagingService { + + @Override + public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { + super.onMessageReceived(remoteMessage); + // Create a MessagingPushPayload object from the remoteMessage + MessagingPushPayload payload = new MessagingPushPayload(remoteMessage); + + // Write your code for creating or using an existing notification channel. + + // Creating an intent and attaching tracking details to it. + Intent intent = new Intent(this, MainActivity.class); + Messaging.addPushTrackingDetails(intent, remoteMessage.getMessageId(), remoteMessage.getData()); + + // Write your code to create a pending intent + + // Create a notification builder + NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this, CHANNEL_ID) + .setSmallIcon(R.drawable.ic_launcher_foreground) + .setContentTitle(payload.getTitle()) + .setContentText(payload.getBody()) + .setAutoCancel(true) + .setContentIntent(pendingIntent); + + // Write your code to add custom buttons to notification, if neccessary. + + // Write your code to download and attach media to notification, if neccessary. + + notificationManager.notify(notificationId, notificationBuilder.build()); + } +} +``` + +## Tracking push notification interactions + +After the application is opened by the user by clicking on the push notification, use the `handleNotificationResponse` API to send the push notification interactions feedback to platform. + +```java + Messaging.handleNotificationResponse( + final Intent intent, // Intent which contains information related to messageId and data + final boolean applicationOpened, // whether application was opened or not + final String actionId) // actionId of the element which performed the custom action. +``` + +##### Sending push notification interaction feedback when application is opened without any custom action + +Add the following code where you have access to `intent` after the user has interacted with the push notification: + +```java +Messaging.handleNotificationResponse(intent, true, null); +``` + +##### Sending feedback when application is opened with a custom action + +Similar to the example above, call the `handleNotificationResponse` API but this time with a custom action: + +```java +Messaging.handleNotificationResponse(intent, true, <actionId>); +``` + +##### Sending feedback when application is not opened but a custom action is performed by the user + +Add the following code where you have access to `intent` after the user has interacted with the push notification: + +```java +Messaging.handleNotificationResponse(intent, false, <actionId>); +``` + +Here is a sample code for sending push notification interactions feedback to platform. + +```java + +public class MainActivity extends AppCompatActivity { + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + final Intent intent = getIntent(); + + // use your unique way to determine isAppOpenFromPushInteraction + if (isAppOpenFromPushInteraction) { + // tracking application opened with no custom action + Messaging.handleNotificationResponse(intent, true, null); + } + } +} +``` diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/index.md b/src/pages/edge/adobe-journey-optimizer/push-notification/index.md new file mode 100644 index 0000000000..f9719a5f3e --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/index.md @@ -0,0 +1,29 @@ +--- +title: Push Notification +description: This guide will walk you through steps necessary to ensure your app is properly implemented for receiving and tracking push notifications with Adobe Journey Optimizer (AJO). +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +--- + +# Push Notification Implementation Guide + +## iOS + +* [Implement Push Message API](./ios/api-reference.md) +* [Displaying rich push notification](./ios/display-rich-notifications.md) + +## Android + +* [Automatic display and tracking of push notification](./android/automatic-display-and-tracking.md) (Recommended) +* [Manual display and tracking of push notification](./android/manual-display-and-tracking.md) + +## Public Classes and Enums + +* [Class - MessagingPushPayload](../public-classes-and-enum/messaging-push-payload.md) (Android only) +* [Enum - PushTrackingStatus](../public-classes-and-enum/push-tracking-status.md) + +## More Information + +* [Push Notification Payload Keys](./push-payload.md) diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/ios/api-reference.md b/src/pages/edge/adobe-journey-optimizer/push-notification/ios/api-reference.md new file mode 100644 index 0000000000..d5a2f9312f --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/ios/api-reference.md @@ -0,0 +1,101 @@ +--- +title: Push Messaging APIs +description: This document details how to use the APIs provided by the AEPMessaging framework for tracking and displaying push notifications. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- iOS +- API +- Tracking +- Push Token +- APNs +--- + +# Push Notification - API reference + +This document details how to use the APIs provided by the AEPMessaging framework for tracking and displaying push notifications. + +## Pre-requisites + +[Integrate and register AEPMessaging extension](../../index.md#implement-extension-in-mobile-app) in your app. + +## Sync the push token + +To retrieve the push token in iOS, refer to the [Apple documentation for registering your app with APNs](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns). Then add the following code to the `application(_: didRegisterForRemoteNotificationsWithDeviceToken:)` method in the `AppDelegate` to sync the device's push token with profile in Adobe Experience Platform. + +<CodeBlock slots="heading, code" repeat="2" languages="Swift, Objective-C" /> + +#### Swift + +```swift +func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { + MobileCore.setPushIdentifier(deviceToken) +} +``` + +#### Objective-C + +```objc +- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { + [AEPMobileCore setPushIdentifier:deviceToken]; +} +``` + +## Track push notification interactions + +Use `handleNotificationResponse` API to send push notification interaction data to Adobe Experience Platform. + +In iOS, [UNUserNotificationCenterDelegate](https://developer.apple.com/documentation/usernotifications/unusernotificationcenterdelegate) is the interface for processing incoming notifications and responding to notification actions. Once the delegate is implemented, handle push notification responses in [userNotificationCenter(_:didReceive:withCompletionHandler:)](https://developer.apple.com/documentation/usernotifications/unusernotificationcenterdelegate/1649501-usernotificationcenter) method. + +<CodeBlock slots="heading, code" repeat="2" languages="Swift, Objective-C" /> + +#### Swift + +```swift +func userNotificationCenter(_: UNUserNotificationCenter, + didReceive response: UNNotificationResponse, + withCompletionHandler completionHandler: @escaping () -> Void) { + Messaging.handleNotificationResponse(response) + completionHandler() +} +``` + +#### Objective-C + +```objc +- (void)userNotificationCenter:(UNUserNotificationCenter *)center +didReceiveNotificationResponse:(UNNotificationResponse *)response + withCompletionHandler:(void (^)(void))completionHandler { + + [AEPMobileMessaging handleNotificationResponse:response closure:nil]; +} +``` + +<InlineAlert variant="info" slots="text"/> + +This API method will automatically handle click behaviour defined for the push notification in Adobe Journey Optimizer. + +#### Reading push tracking status + +Implement the callback in `handleNotificationResponse` API to read [PushTrackingStatus](../enum-push-tracking-status.md) enum representing tracking status of the push notification. + +<CodeBlock slots="heading, code" repeat="2" languages="Swift, Objective-C" /> + +#### Swift + +```swift + Messaging.handleNotificationResponse(response) { trackingStatus in + // handle the different values of trackingStatus + } +``` + +#### Objective-C + +```objc + [AEPMobileMessaging handleNotificationResponse:response closure:^(AEPPushTrackingStatus status){ + if (status == AEPPushTrackingStatusTrackingInitiated) { + NSLog(@"Successfully started push notification tracking"); + } + }]; +``` diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/ios/display-rich-notifications.md b/src/pages/edge/adobe-journey-optimizer/push-notification/ios/display-rich-notifications.md new file mode 100644 index 0000000000..246ba8b2fb --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/ios/display-rich-notifications.md @@ -0,0 +1,103 @@ +--- +title: Displaying rich push notification +description: This document details how to display media notification on iOS device for notification generated from Adobe Journey Optimizer. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +- iOS +--- + +# Displaying rich push notification + +This document details how to handle and display media notification on iOS device for notification generated from Adobe Journey Optimizer. + +Follow Apple's documentation to [add a notification service app extension to your project](https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications#2942063). Then use the service app extension to download images or other media attachments for the notification before displaying it on user's iOS device. + +## Notification service extension implementation + + Notifications from Adobe Journey Optimizer contain a media attachment URL in the `adb_media` key of the notification payload. Use the service extension to download the media attachment from the URL and attach it to the notification before displaying it on the user's device. + + Here is an example implementation: + +```swift +import UserNotifications + +class NotificationService: UNNotificationServiceExtension { + + var contentHandler: ((UNNotificationContent) -> Void)? + var bestAttemptContent: UNMutableNotificationContent? + + override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { + self.contentHandler = contentHandler + bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent) + + // defer this block to be executed to call the callback + defer { + contentHandler(bestAttemptContent ?? request.content) + } + + guard let attachment = request.adobeAttachment else { return } + bestAttemptContent?.attachments = [attachment] + + } + + override func serviceExtensionTimeWillExpire() { + // Called just before the extension will be terminated by the system. + // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used. + if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent { + contentHandler(bestAttemptContent) + } + } + +} + +extension UNNotificationRequest { + var adobeAttachment: UNNotificationAttachment? { + // return nil if the notification does not contain a valid value for adb_media key + guard let attachmentString = content.userInfo["adb_media"] as? String else { + return nil + } + + // do not attach anything if it is not a valid URL + guard let attachmentURL = URL(string: attachmentString) else { + return nil + } + + // do not attach anything if the url does not contain downloadable data + guard let attachmentData = try? Data(contentsOf: attachmentURL) else { + return nil + } + + return try? UNNotificationAttachment(data: attachmentData, options: nil, attachmentURL: attachmentURL) + } +} + +extension UNNotificationAttachment { + + /// Convenience initializer to create a UNNotificationAttachment from a URL + /// - Parameters: + /// - data: the data to be displayed in the notification + /// - options : options for the attachment + /// - attachmentURL : the URL of the rich media to be displayed in the notification + convenience init(data: Data, options: [NSObject: AnyObject]?, attachmentURL: URL) throws { + let fileManager = FileManager.default + let temporaryFolderURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(ProcessInfo.processInfo.globallyUniqueString, + isDirectory: true) + try fileManager.createDirectory(at: temporaryFolderURL, withIntermediateDirectories: true, attributes: nil) + var attachmentType : String + + // determine the attachment type from the url + // common format are png, jpg, gif, mp3, mpeg4, avi, mp4 + // Reference Apple documentation for supported file types and maximum size : https://developer.apple.com/documentation/usernotifications/unnotificationattachment + /// NOTE : Please edit the below code according to the type of rich media notification that your app needs to support + attachmentType = ".jpg" + + let attachmentName = UUID().uuidString + attachmentType + let fileURL = temporaryFolderURL.appendingPathComponent(attachmentName) + try data.write(to: fileURL) + try self.init(identifier: attachmentName, url: fileURL, options: options) + } + +} +``` diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/push-payload.md b/src/pages/edge/adobe-journey-optimizer/push-notification/push-payload.md new file mode 100644 index 0000000000..6551afa5a0 --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/push-payload.md @@ -0,0 +1,24 @@ +--- +title: Push Notification Payload +description: This document outlines the various push notification payload keys used by the Adobe Journey Optimizer. +keywords: +- Adobe Journey Optimizer +- Messaging +- Push Notification +--- + +import Tabs from './tabs/push-payload.md' + +# Push Notification Payload Keys + +This document outlines the various push notification payload keys used by the Adobe Journey Optimizer. + +<TabsBlock orientation="horizontal" slots="heading, content" repeat="2"/> + +Android + +<Tabs query="platform=android&api=payload-keys"/> + +iOS + +<Tabs query="platform=ios&api=payload-keys"/> diff --git a/src/pages/edge/adobe-journey-optimizer/push-notification/tabs/push-payload.md b/src/pages/edge/adobe-journey-optimizer/push-notification/tabs/push-payload.md new file mode 100644 index 0000000000..82762e376f --- /dev/null +++ b/src/pages/edge/adobe-journey-optimizer/push-notification/tabs/push-payload.md @@ -0,0 +1,94 @@ +--- +noIndex: true +--- + +<Variant platform="android" api="payload-keys" repeat="3"/> + +* Adobe Journey Optimizer uses [data messages](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) with custom key-value pairs to send push notifications to client apps. +* When using [manual display and tracking](../android/manual-display-and-tracking.md), use the [MessagingPushPayload](../../public-classes-and-enum/messaging-push-payload.md) class to extract the payload values. + +```json +{ + "message":{ + "android":{ + "collapse_key": "new_message", + "priority": "HIGH", + "data":{ + "adb_title":"Game Request", + "adb_body":"Bob wants to play chess", + "adb_sound" : "somesound_res", + "adb_n_count" : "3", + "adb_n_priority" : "PRIORITY_LOW", + "adb_channel_id": "cid", + "adb_icon" : "notification_icon", + "adb_image": "www.imageUrl.com", + "adb_a_type": "DEEPLINK/WEBURL/OPENAPP", + "adb_uri" : "deeplinkurl/weburl", + "adb_act": [ + { + "label" : "deeplink", + "uri" : "notificationapp://", + "type" : "DEEPLINK" + }, + { + "label" : "weburl", + "uri" : "https://www.yahoo.com", + "type" : "WEBURL" + } + ], + "some_custom_data_key": "some data" + } + } + } +} +``` + +| **Key** | **Type** | **Description** | +| :------ | :------- | :-------------- | +| `adb_title` | String | The push notification's title | +| `adb_body` | String | The push notification's body | +| `adb_sound` | String | The push notification's sound | +| `adb_n_count` | String | The push notification badge count | +| `adb_n_priority` | String | The push notification's priority. For more information, please read the [Firebase documentation](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notificationpriority) | +| `adb_channel_id` | String | The push notification's channel ID | +| `adb_icon` | String | The push notification's icon resource name | +| `adb_image` | String | The URL of the image to be displayed on the notification | +| `adb_a_type` | enum | An enum that determines what type of action will be performed when the notification is clicked. It can be one of the following values: `DEEPLINK`, `WEBURL`, or `OPENAPP`. | +| `adb_uri` | String | The URI used for deeplinking. The deeplink is used to open the appropriate webpage or app screen when the notification is clicked. | +| `adb_act` | Array | An array that contains the action object(s). | +| `adb_act.label` | String | The label for custom action button | +| `adb_act.uri` | String | The URI for custom action button | +| `adb_act.type` | enum | The action type for custom action button. It can be one of the following values: `DEEPLINK`, `WEBURL`, `OPENAPP` | + +<Variant platform="ios" api="payload-keys" repeat="2"/> + +```json +{ + "aps":{ + "alert":{ + "title": "Hello from CJM", + "body": "Stay safe, wear a mask" + }, + "sound": "dingDong", + "badge":2, + "mutable-content":1, + "category": "iosCategory", + "thread-id": "myGroup", + "content-available":1 + }, + "some_custom_data_key": "some data", + "adb_media": "www.imageUrl.com", + "adb_a_type": "DEEPLINK/WEBURL/OPENAPP", + "adb_uri": "deeplinkUrl/weburl", +} +``` + +| **Key** | **Type** | **Description** | +| :------ | :------- | :-------------- | +| `adb_media` | String | The URL of the media. In this situation, media refers to either an image or a video. This URL can be used to download the rich media before showing the push notification. | +| `adb_uri` | String | The URI used for deeplinking. The deeplink is used to open appropriate webpage or app screen when the notification is clicked. | +| `adb_a_type` | enum | An enum that determines what type of action will be performed when the notification is selected. It can be one of the following string values: `DEEPLINK`, `WEBURL`, `OPENAPP`. | +| `adb_act` | Array | An array that contains the action object(s). | +| `adb_act.aid` | String | The ID for the action object. | +| `adb_act.label` | String | The name for the action object | +| `adb_act.type` | String | The type for the action object. It can be one of the following string values: `DEEPLINK`, `WEBURL`, `DISMISS` | diff --git a/src/pages/edge/adobe-journey-optimizer/tabs/api-reference.md b/src/pages/edge/adobe-journey-optimizer/tabs/api-reference.md index 6afeddc1bb..f083d5f21e 100644 --- a/src/pages/edge/adobe-journey-optimizer/tabs/api-reference.md +++ b/src/pages/edge/adobe-journey-optimizer/tabs/api-reference.md @@ -48,14 +48,16 @@ public static let extensionVersion [AEPMobileMessaging extensionVersion]; ``` -<Variant platform="android" api="handle-notification-response" repeat="6"/> +<Variant platform="android" api="handle-notification-response" repeat="4"/> #### Java **Syntax** ```java -public static void handleNotificationResponse(final Intent intent, final boolean applicationOpened, final String customActionId); +public static void handleNotificationResponse(final Intent intent, + final boolean applicationOpened, + final String customActionId); ``` | **Parameter** | **Type** | **Description** | @@ -64,39 +66,16 @@ public static void handleNotificationResponse(final Intent intent, final boolean | `applicationOpened` | Boolean | Shows whether the application has been opened or not. | | `actionId` | String | The ID of the custom action. | -**Example** - -```java -// Intent can be retrieved from the Activity/BroadcastReceiver using the getIntent() method. -Intent intent = getIntent(); -Messaging.handleNotificationResponse(intent, true, "customActionId"); -``` - -<Variant platform="ios" api="handle-notification-response" repeat="11"/> +<Variant platform="ios" api="handle-notification-response" repeat="7"/> #### Swift **Syntax** ```swift -static func handleNotificationResponse(_ response: UNNotificationResponse, applicationOpened: Bool, customActionId: String?) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `response` | UNNotificationResponse | An object containing information about the push notification details. | -| `applicationOpened` | Boolean | Shows whether the application has been opened or not. | -| `customActionId` | String | The ID of the custom action. | - -**Example** - -```swift -func userNotificationCenter(_: UNUserNotificationCenter, - didReceive response: UNNotificationResponse, - withCompletionHandler completionHandler: @escaping () -> Void) { - Messaging.handleNotificationResponse(response, applicationOpened: true, customActionId: "customActionId") - completionHandler() -} +static func handleNotificationResponse(_ response: UNNotificationResponse, + applicationOpened: Bool, + customActionId: String?) ``` #### Objective-C @@ -104,21 +83,16 @@ func userNotificationCenter(_: UNUserNotificationCenter, **Syntax** ```objc -@objc(handleNotificationResponse:applicationOpened:withCustomActionId:) -static func handleNotificationResponse(_ response: UNNotificationResponse, applicationOpened: Bool, customActionId: String?) ++ (void)handleNotificationResponse:(UNNotificationResponse *)response + applicationOpened: (BOOL)applicationOpened + customActionId: (NSString *)customActionId; ``` -**Example** - -```objc -- (void)userNotificationCenter:(UNUserNotificationCenter *)center -didReceiveNotificationResponse:(UNNotificationResponse *)response - withCompletionHandler:(void (^)())completionHandler { - // Your code - [AEPMobileMessaging handleNotificationResponse:response applicationOpened:true withCustomActionId:@"customActionId"]; - completionHandler(); -} -``` +| **Parameter** | **Type** | **Description** | +| :----------- | :------- | :-------------- | +| `response` | UNNotificationResponse | An object containing information about the push notification details. | +| `applicationOpened` | Boolean | Shows whether the application has been opened or not. | +| `customActionId` | String | The ID of the custom action. | <Variant platform="android" api="register-extension" repeat="5"/> @@ -136,105 +110,16 @@ public static void registerExtension(); Messaging.registerExtension(); ``` -<Variant platform="android" api="refresh" repeat="2"/> - -#### Java - -```java -Messaging.refreshInAppMessages(); -``` - -<Variant platform="ios" api="refresh" repeat="2"/> - -#### Swift - -```swift -Messaging.refreshInAppMessages() -``` - -<Variant platform="android" api="set-push-identifier" repeat="7"/> - -To retrieve the push token from Firebase Messaging Service, please follow the tutorial within the [Firebase documentation](https://firebase.google.com/docs/cloud-messaging/android/client#retrieve-the-current-registration-token). +<Variant platform="android" api="add-push-tracking-details" repeat="5"/> #### Java **Syntax** ```java -public static void setPushIdentifier(final String pushIdentifier); -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `pushIdentifier` | String | The push token that is synced with Adobe Experience Platform. | - -**Example** - -```java -FirebaseMessaging.getInstance().getToken() - .addOnCompleteListener(new OnCompleteListener<String>() { - @Override - public void onComplete(@NonNull Task<String> task) { - if (task.isSuccessful()) { - String token = task.getResult(); - MobileCore.setPushIdentifier(token); - } - } - }); -``` - -<Variant platform="ios" api="set-push-identifier" repeat="13"/> - -To retrieve the push token in iOS, please read the tutorial within [Apple's documentation](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns). - -#### Swift - -**Syntax** - -```swift -public static func setPushIdentifier(_ deviceToken: Data?) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `deviceToken` | Data | The push token that is synced with Adobe Experience Platform. | - -**Example** - -```swift -func application(_: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { - MobileCore.setPushIdentifier(deviceToken) -} -``` - -#### Objective-C - -**Syntax** - -```objc -public static func setPushIdentifier(_ deviceToken: Data?) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `deviceToken` | Data | The push token that is synced with Adobe Experience Platform. | - -**Example** - -```objc -- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { - [AEPMobileCore setPushIdentifier:deviceToken]; -} -``` - -<Variant platform="android" api="add-push-tracking-details" repeat="7"/> - -#### Java - -**Syntax** - -```java -public static boolean addPushTrackingDetails(final Intent intent, final String messageId, final Map<String, String> data) +public static boolean addPushTrackingDetails(final Intent intent, + final String messageId, + final Map<String, String> data) ``` | **Parameter** | **Type** | **Description** | @@ -245,212 +130,6 @@ public static boolean addPushTrackingDetails(final Intent intent, final String m This API returns a boolean, indicating whether the intent was updated with necessary information (messageId and Customer Journey data). -**Example** - -```java -boolean success = addPushTrackingDetails(intent, messageId, data) -``` - -<Variant platform="android" api="messaging-push-payload" repeat="8"/> - -#### Java - -**Syntax** - -```java -public MessagingPushPayload(RemoteMessage message) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `message` | `RemoteMessage` | A message that contains the necessary attributes for creating a push notification. | - -```java -public MessagingPushPayload(Map<String, String> data) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `data` | `Map<String, String>` | A data payload that contains the necessary attributes for creating a push notification. | - -**Examples** - -```java -// Using the remote message -@Override -public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { - MessagingPushPayload payload = new MessagingPushPayload(remoteMessage); -} - -// Using the data map -@Override -public void onMessageReceived(@NonNull RemoteMessage remoteMessage) { - MessagingPushPayload payload = new MessagingPushPayload(remoteMessage.getData()); -} -``` - -<Variant platform="android" api="public-apis" repeat="8"/> - -#### Java - -**Syntax** - -```java -// Returns the title from the remote message -public String getTitle() - -// Returns the body from the remote message -public String getBody() - -// Returns the sound from the remote message -// The sound string represents the filename of a sound resource bundled in the app. -public String getSound() - -// Returns the notification badge count from the remote message -public int getBadgeCount() - -// Returns the notification priority from the remote message. -// For more information, please read the Firebase documentation (https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notificationpriority) -public int getNotificationPriority() - -// Returns the channel ID from the remote message. -public String getChannelId() - -// Returns the icon string from the remote message. -// The icon string represents the drawable resource name in the app. -public String getIcon() - -// Returns the image URL from the remote message. -public String getImageUrl() - -// Returns the data map from the remote message. -public Map<String, String> getData() - -// Returns an ActionType object which represents the type of action which needs to be performed on push notification interaction. -// More information about the ActionType enum definition can be found in the ActionType section below. -public ActionType getActionType() - -// Returns the action URI as a string. The action URI is used to direct the push notification interaction. -public String getActionUri() - -// Returns a list of ActionButtons. More information about the ActionButtons class definition can be found in the ActionButtons section below. -public List<ActionButton> getActionButtons() -``` - -**Internal classes and enums** - -**ActionType** - -```java -public enum ActionType { - DEEPLINK, WEBURL, OPENAPP, NONE -} -``` - -**ActionButtons** - -```java -// Constructor -public ActionButton(final String label, final String link, final String type) - -// Public APIs - -// Returns the label for the action button -public String getLabel() - -// Returns the link for the action button -public String getLink() - -// Returns the ActionType for the action button -public ActionType getType() -``` - -<Variant platform="android" api="payload-keys" repeat="3"/> - -You should use the `MessagingPushPayload` class to extract the payload values. - -```json -{ - "message":{ - "android":{ - "collapse_key": "new_message", - "priority": "HIGH", - "data":{ - "adb_title":"Game Request", - "adb_body":"Bob wants to play chess", - "adb_sound" : "somesound_res", - "adb_n_count" : "3", - "adb_n_priority" : "PRIORITY_LOW", - "adb_channel_id": "cid", - "adb_icon" : "notification_icon", - "adb_image": "www.imageUrl.com", - "adb_a_type": "DEEPLINK/WEBURL/OPENAPP", - "adb_uri" : "deeplinkurl/weburl", - "adb_act": [ - { - "label" : "deeplink", - "uri" : "notificationapp://", - "type" : "DEEPLINK" - }, - { - "label" : "weburl", - "uri" : "https://www.yahoo.com", - "type" : "WEBURL" - } - ], - "some_custom_data_key": "some data" - } - } - } -} -``` - -| **Key** | **Type** | **Description** | -| :------ | :------- | :-------------- | -| `adb_title` | String | The push notification's title | -| `adb_body` | String | The push notification's body | -| `adb_sound` | String | The push notification's sound | -| `adb_n_count` | String | The push notification badge count | -| `adb_n_priority` | String | The push notification's priority. For more information, please read the [Firebase documentation](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notificationpriority) | -| `adb_channel_id` | String | The push notification's channel ID | -| `adb_icon` | String | The push notification's icon resource name | -| `adb_image` | String | The URL of the image to be displayed on the notification | -| `adb_a_type` | enum | An enum that determines what type of action will be performed when the notification is clicked. It can be one of the following values: `DEEPLINK`, `WEBURL`, or `OPENAPP`. | -| `adb_uri` | String | The URI used for deeplinking. The deeplink is used to open the appropriate webpage or app screen when the notification is clicked. | -| `adb_act` | Array | An array that contains the action object(s). | -| `adb_act.label` | String | The label for custom action button | -| `adb_act.uri` | String | The URI for custom action button | -| `adb_act.type` | enum | The action type for custom action button. It can be one of the following values: `DEEPLINK`, `WEBURL`, `OPENAPP` | - -<Variant platform="ios" api="payload-keys" repeat="2"/> - -```json -{ - "aps":{ - "alert":{ - "title": "Hello from CJM", - "body": "Stay safe, wear a mask" - }, - "sound": "dingDong", - "badge":2, - "mutable-content":1, - "category": "iosCategory", - "thread-id": "myGroup", - "content-available":1 - }, - "some_custom_data_key": "some data", - "adb_media": "www.imageUrl.com", - "adb_a_type": "DEEPLINK/WEBURL/OPENAPP", - "adb_uri": "deeplinkUrl/weburl", -} -``` +<Variant platform="iOS" api="add-push-tracking-details" repeat="1"/> -| **Key** | **Type** | **Description** | -| :------ | :------- | :-------------- | -| `adb_media` | String | The URL of the media. In this situation, media refers to either an image or a video. This URL can be used to download the rich media before showing the push notification. | -| `adb_uri` | String | The URI used for deeplinking. The deeplink is used to open appropriate webpage or app screen when the notification is clicked. | -| `adb_a_type` | enum | An enum that determines what type of action will be performed when the notification is selected. It can be one of the following string values: `DEEPLINK`, `WEBURL`, `OPENAPP`. | -| `adb_act` | Array | An array that contains the action object(s). | -| `adb_act.aid` | String | The ID for the action object. | -| `adb_act.label` | String | The name for the action object | -| `adb_act.type` | String | The type for the action object. It can be one of the following string values: `DEEPLINK`, `WEBURL`, `DISMISS` | +This API is not applicable for iOS. \ No newline at end of file diff --git a/src/pages/edge/adobe-journey-optimizer/tabs/index.md b/src/pages/edge/adobe-journey-optimizer/tabs/index.md index f903694831..45483c6b22 100644 --- a/src/pages/edge/adobe-journey-optimizer/tabs/index.md +++ b/src/pages/edge/adobe-journey-optimizer/tabs/index.md @@ -139,78 +139,3 @@ func application(_ application: UIApplication, didFinishLaunchingWithOptions lau ... } ``` - -<Variant platform="android" task="sync" repeat="7"/> - -To retrieve the push token from Firebase Messaging Service, please read the tutorial on [retrieving the registration token](https://firebase.google.com/docs/cloud-messaging/android/client#retrieve-the-current-registration-token) within the Firebase documentation. After retrieving the push token, you can use the following API to sync it with Profile in Platform. - -#### Java - -**Syntax** - -```java -public static void setPushIdentifier(final String pushIdentifier); -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `pushIdentifier` | String | The push token value. | - -**Example** - -```java -FirebaseMessaging.getInstance().getToken() - .addOnCompleteListener(new OnCompleteListener<String>() { - @Override - public void onComplete(@NonNull Task<String> task) { - if (task.isSuccessful()) { - String token = task.getResult(); - MobileCore.setPushIdentifier(token); - } - } - }); -``` - -<Variant platform="ios" task="sync" repeat="13"/> - -#### Swift - -To retrieve the push token in iOS, please read the tutorial on [registering your application](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns) within Apple's documentation. After retrieving the push token, you can use the following API to sync it with Profile in Platform. - -**Syntax** - -```swift -public static func setPushIdentifier(_ deviceToken: Data?) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `deviceToken` | Data | The push token value. | - -**Example** - -```swift -func application(_: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { - MobileCore.setPushIdentifier(deviceToken) -} -``` - -#### Objective-C - -**Syntax** - -```objc -public static func setPushIdentifier(_ deviceToken: Data?) -``` - -| **Parameter** | **Type** | **Description** | -| :----------- | :------- | :-------------- | -| `deviceToken` | Data | The push token value. | - -**Example** - -```objc -- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { - [AEPMobileCore setPushIdentifier:deviceToken]; -} -```