This document is intended to describe the structure of the payload received in mobile applications when a push notification is successfully sent to an app from Adobe Campaign Standard. This document will also cover the explanation for each of the attributes that may be received in the push notification payload.

Introduction

Adobe Campaign allows you to send personalized and segmented push notifications on iOS and Android mobile devices to mobile applications (mobile app). Every push notification that is received on a mobile app carries some information which is used by the app to display the push notification if an Alert push notification is sent, and most likely to also do some further computation, especially if a silent push notification is sent. This information is received by the mobile app code in an event handler that indicates that a push notification was received. When sending push notifications from Adobe Campaign Standard, the information received in the mobile app may also contain Campaign Standard specific information which may be used to leverage some features provided by Campaign Standard. Additionally, the payload can contain custom data that can be consumed by the mobile app.

This document, will describe the structure of the payload received in a mobile app, when a push notification is successfully sent to an app from Adobe Campaign Standard.

Note:

The payload structure varies depending on the type of mobile app (i.e. iOS app, GCM-enabled Android app or FCM-enabled Android app). 

Target audience

An iOS or Android mobile app developer with knowledge of Adobe Campaign Standard Push Notifications.

Prerequisites

Push payload structure

This section demonstrates a structure of a sample payload for various mobile platforms and describes major attributes that are contained in it. This is the structure of the payload when it is received in the mobile app code in the event handler that indicates that a push notification has been received. The payload attributes and their values will vary based on the configurations provided in Push notification advanced options. This section also provides a mapping between these configurations in Campaign Standard UI and the attributes in the payload in order to clarify how the payload will change on configuring an option in Campaign Standard.

For iOS Mobile App

Sample Payload

{

    "aps"={

            "alert"={

                    "body"="This is the content of my push notification";

                    "title"="Push Notification Title";

            };

            "content-available"=1;

            "category"="NEW_MESSAGE_CATEGORY";

            "badge"=2;

            "mutable-content"=1;

            "sound"="default";

        };

    "custom_field1"="custom_value1";

    "custom_field2"="custom_value2";

    "media-attachment-url"="https://2.img-dpreview.com/files/p/articles/9440145363/Creative_Cloud.jpeg";

    "uri"="https://mydeeplinkurl.com";

    "_dId"=56c4;

    "_mId"=h138a;

}

The most important section of the payload is the aps dictionary, which contains Apple-defined keys and is used to determine how the system receiving the notification should alert the user, if at all. This section contains pre-defined keys that are used by the mobile app to formulate the behavior of the push notification.

In-depth details on the attributes within aps can be found in Apple developer docs: Creating the Remote Notification Payload. (If Apple developer page does not exist, saved the page as a PDF as of May 1, 2018: Creating the Remote Notification Payload.pdf)

For Android App

Sample Payload

{

    custom_field1=custom_value1,

    custom_field2=custom_value2,

    google.sent_time=1508439042418,

    google.message_id=0:1508439042462113%0ce48b6b0ce48b6b,

    collapse_key=com.adobe.campaign.pushTester,  

    e=1,

    badge=212,

    sound=default,

    title=Push Notification Title,

    body=This is the content of my push notification,

    sound2=default,

    media-attachment-url=http://www.gstatic.com/webp/gallery/2.jpg,

    _dId=56c4,

    _mId=h1f40,

    uri=https://mydeeplinkurl.com,

    category=NEW_MESSAGE_CATEGORY

}

The payload contains data message which includes all the push notification delivery content including the custom key/value pairs, and the client app must handle the message to build and show push notification, if required or else to add any other business logic. 

To understand aspects of an android payload refer to Messaging Concepts and Options (gcm) or Messaging Concepts and Options (fcm). If this page does not exist, save the page as a PDF as of May 1, 2018: Messaging Concepts and Options (fcm).pdf)

Note:

Support for Notification messages in Android payload was removed as of 2018 to enable waking up of the App and passing control to the mobile App without needing user to interact with the App.

Mapping between Campaign Standard Configurations and Payload Attributes

Campaign Standard Configuration Impacted Attribute in iOS Impacted Attribute in Android Description

Message title

Message body

alert → title

alert → body

title

body

This data contains specifics of the alert message.

The title and body keys provide the contents of the alert.

Play a sound
sound sound A custom sound to play with the alert.
Value of the badge badge badge An integer value to be used to badge the app’s icon.
Add a deeplink
uri   A deeplink enables you to bring the users directly to content located inside the application (instead of opening a web browser page).
Category category category To display custom actions with a remote notification. The category key helps the system display the actions for that category as buttons in the alert interface.
Custom fields
custom_field1, custom_field2 ... custom_field1, custom_field2 ... Any custom data that you want to send to your app.

Rich media content URL (image, gif, audio and video files)

(Only applicable for iOS 10 or higher)

media-attachment-url NA

URL of your media files to add rich content to your notification.

On providing a value for this URL, the mutable-content flag is automatically sent into the payload.

(Only applicable for iOS 10 or higher)

Mutable Content

(Only applicable for iOS 10 or higher)

mutable-content
NA

The Notification Service Extension in your app will "intercept" all remote notifications with the mutable-content key and will allow you to handle/manipulate the contents of the request payload, which can then be used to customize the notification. Use cases of this feature include downloading and displaying multiple media, decrypting any encrypted data present in the push payload. More information can be found at Modify the payload of a Remote Notification

(Only applicable for iOS 10 or higher)

 Content Available
 content-available
NA Selecting this option enables waking up of an iOS app while it is in background/suspended state. Waking up implies that the app runs in the background and the appropriate event handler responsible for receiving the push notification data payload gets a control and can use the data to do any computation, including but not limited to building custom push notification and displaying the same. More information can be found at Wake up App with Notification delivery

Rich media content URL (image files)

(Only applicable forAndroid)

NA media-attachment-url
URL of your image files to add rich content to your notification.
NA

_mId

_dId

_mId

_dId

This is the value of broadlogId

This is the value of deliveryId

These attributes are required if your app wishes to call a tracking postback to track when the push notification was clicked/opened. This information is computed and sent internally by the app server without user intervention.

Information on postbacks can be found at: Integrate the Adobe Mobile SDK with a mobile app to receive Campaign Standard push notifications

How to retrieve payload information in mobile app code

The payload information that is sent by the app server is received by the mobile app code in an event handler that indicates that a push notification was received. This event would vary based on the mobile platform being worked upon and also based on whether the app is running in foreground or background. The following documentation will help you identify the event handler you wish to handle based on your use case. 

Sample for iOS Mobile App

 - (void)application:(UIApplication *)application

didReceiveRemoteNotification:(NSDictionary *)userInfo {

    

    NSDictionary *apsDict = [userInfo objectForKey:@"aps"];

    NSDictionary *alertDict = [apsDict objectForKey:@"alert"];

    NSString *title = [alertDict objectForKey:@"title"];

    NSString *body = [alertDict objectForKey:@"body"];

    NSString *category = [apsDict objectForKey:@"category"];

    NSString *deliveryId = userInfo[@"_dId"];

    NSString *broadlogId = userInfo[@"_mId"];

    NSString *mediaAttachmentURL = userInfo[@"media-attachment-url"];

    NSString *deeplinkURL = userInfo[@"uri"];

    NSString *customValue1 = userInfo[@"custom_field1"];   

}

Sample for Android Mobile GCM App

public void onMessageReceived(String from, Bundle data) {

    

    String title = data.getString("title");

    String body = data.getString("body");

    String category = data.getString("category");

    String deliveryId = data.getString("_dId");

    String broadlogId = data.getString("_mId");

    String mediaAttachmentURL = data.getString("media-attachment-url");

    String deeplinkURL = data.getString("uri");

    String customValue1 = data.getString("custom_field1");

}

Sample for Android Mobile FCM App

public void onMessageReceived(RemoteMessage message) {

    Map<String, String> dataMap = message.getData();

     

    String title = dataMap.get("title");

    String body = dataMap.get("body");

    String category = dataMap.get("category");

    String deliveryId = dataMap.get("_dId");

    String broadlogId = dataMap.get("_mId");

    String mediaAttachmentURL = dataMap.get("media-attachment-url");

    String deeplinkURL = dataMap.get("uri");

    String customValue1 = dataMap.get("custom_field1");

}

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy