Message Center on Android

Mobile App Message Center enables Marketers to persist their sent Push campaign messages, so that mobile app users can view them later in the mobile app. Mobile App Developers can fetch these messages from Responsys and display them to mobile app users.

In this topic:

The Oracle Responsys Mobile App Platform Cloud Service SDK provides an API for fetching the Message Center messages data from Responsys. You must work with the Marketing team to design and develop the user experience in your mobile app.

BEFORE YOU BEGIN:

Request access to the Message Center feature by contacting your Customer Success Manager or logging in to My Oracle Support and creating a service request. This feature is currently released under our Controlled Availability program.
Your mobile app must use the Oracle Responsys Mobile App Platform Cloud Service SDK version 6.39 (18D) or later. Oracle recommends that your mobile app always use the latest SDK.

Platform-specific topics: This topic provides Developer information common to all platforms. To view information for the platform(s) you support for your mobile app, refer to the topics for each supported platform:

iOS 8 and greater (Click to view the iOS Message Center topic)
Android 4 and greater (Click to view the Android Message Center topic)

How Message Center Works

Message Center requires implementation by the Mobile App Developers, and it must be enabled in a Push Campaign by Marketers using Responsys. Responsys and the mobile app interact at runtime to provide the messages to a known user or device. This section provides details about how Message Center is set up and how it behaves at runtime.

Development

The Responsys Integrated Push customer decides to implement Message Center and submits a service request to Oracle Support.
Oracle enables the customer’s Responsys account for Message Center.
Mobile App Developers create the user experience in their mobile app, with input from the Marketing team.
If the team requires additional custom message centers, Mobile App Developers log in to the Mobile App Developer Console and add message centers to their mobile app. You can add up to four message centers. (Responsys supports five message centers total: Primary plus four custom message centers.)
Mobile App Developers add the SDK call for fetching messages to their code, and then handle the response from Responsys. Depending on your mobile app design, you may choose to use all or some of the data that Responsys returns to the mobile app.

Campaign Design

Marketers use the Push Message Designer in Responsys to design their Push campaign, or, as of 18D, they can create a Message Center campaign. They select whether Responsys should save their Push campaign to the Message Center after the campaign launch, and they configure additional information about the message, such as the subject, message icon, message center name (if using one other than Primary), and message expiration date. Campaign messages are available to the mobile apps for a Message Center campaign, but a Push notification is not sent to mobile app users.

Runtime

Marketers launch the campaign. If the Message Center message is part of a Push campaign, Responsys sends the Push notification to the audience that the Marketers define. Otherwise, the Message Center message becomes available for the next fetch from the mobile apps.
If the Message Center message is part of a Push campaign, mobile app users receive the Push notification.
On the first mobile app launch after installation, and at fixed intervals after that (currently every five minutes), the SDK can fetch messages from Responsys. The SDK will cache the messages on the device. Responsys returns a list of up to 20 for each Message Center defined for the app. These messages are the most recent and unexpired messages stored in the message center, for either a logged-in user or for this specific device. The messages received may vary, depending on whether the user is logged in to the app. Processing occurs in the background, and the user can continue using in the app.
The mobile app user access the Message Center in the mobile app.
The mobile app displays the cached messages.
- If the mobile app user is logged in, then the mobile app has set the USER_IDENTIFIER to that user. All messages that Responsys returns are the logged-in (known) app user.
- If the mobile app user is not logged in, then the resulting messages are those meant for this device / all logged out (unknown) users. We use the DEVICE_ID to identify such messages. For unknown or logged out users, we expect the USER_IDENTIFIER to be set to null.
The mobile app user sees the messages listed in the mobile app’s Message Center.
If the Message Center message is part of a Push campaign, and depending on the Push Notification Action defined by the Marketer, App Developers could build varying user experiences for mobile app users. Expected actions for each type:
- Launch App – Display the message in the Message Center list.
- Open URL – Display the message in the Message Center list. When the mobile app user clicks the message, the Deep link opens to the URL the marketer entered, typically a section within the mobile app.
- Open Rich Message – Display the message in the Message Center list. When the mobile app user clicks the message, the mobile app displays the rich HTML message that was sent in the original Push notification.

App Icon Badges

App Icon Badges are supported through Message Center messaging Campaigns. Marketers can display a Badge Count on the App Icon on an end user's device to indicate the number of new Message Center messages available to the app user. Marketers can increment, specify a value, or clear the Badge Count for every message sent to the user's device. App Icon Badging with Message Center Messages can increase app user engagement rates.

Development Notes

Reminder - To use Message Center, a Responsys account must be enabled for Message Center.
Obtain the latest version of the SDK for your supported platforms. All developers working on the mobile app must use the same SDK version (current SDK recommended; minimum SDK 6.39.0 or later).
You must turn on Message Center in your code, using the SDK's setMessageCenterEnabled method. This applies even if you are already using SDK 6.37.0 or later OR are upgrading from an older SDK version to SDK version 6.39.0 or later. Please see the platform-specific Message Center topics for details.
Work with the Responsys Marketer to design the Message Center user interface for your mobile app. For example, Message Center supports Subject (Title) and Message Icon, but those may not be desired features.
We support five Message Centers per app, including Primary (the system default). You may add up to four additional message centers.
Message Center is not available during Responsys downtime, such as planned maintenance events.
Responsys provides the Message Center messages to the mobile app, but the SDK cannot inform Responsys about read, unread, and deleted messages.

Fetching Messages from Message Center

This section describes how the SDK obtains the messages and the data Responsys that are available to your mobile app. The platform-specific sections describe how to use the calls described in this section in mobile apps supporting iOS and Android.

Messages are pre-fetched (for all Message Centers) when the application is first launched after installation. Thereafter, messages are refreshed at fixed intervals (currently every five minutes). If the mobile app user exits the mobile app and then re-opens it, the SDK refreshes Message Center messages from Responsys only if it is due for a refresh.

Data fetched may vary as follows:

If the USER_IDENTIFIER is set by the mobile app, then Message Center messages are retrieved for the USER_IDENTIFIER. (USER_IDENTIFIER corresponds to the match key set in Responsys, which links the App Channel List record with a known recipient in the Profile List.)
Otherwise, Message Center messages are retrieved for the DEVICE_ID.

When your mobile app calls fetchMessageForMessageCenter, the SDK fetches messages from the SDK's managed local storage. Once the mobile app fetches a list of messages by calling fetchMessagesForMessageCenter, the app must maintain its own storage for the fetched messages.

Transactions with the Responsys servers are asynchronous. The SDK and Responsys process the calls in the background, and the user can continue using the app.

Using the Cached Messages

When the SDK pre-fetches the messages, Responsys returns the most recent 20 non-expired Message Center messages for each Message Center configured for the app, the user, or device:

If user is logged in (known), Responsys uses the USER_IDENTIFIER to obtain messages.
If user is not logged in (unknown), Responsys uses the DEVICE_ID to obtain messages.

Data retention policy

The duration Oracle caches Message Center messages are subject to change at anytime. Currently, messages are retained for 7 days from the fetched date, and then they are deleted. Apps should not rely on the SDK cache to act as storage for their app's Message Center messages. Apps must maintain their own storage and be developed to either retain messages for as long as messages are required or delete messages when no longer needed. Each message has a unique message ID. Apps should check a message's ID to check whether or not the app has already retrieved and stored a message.

Retrieving rich content

Your mobile app needs to fetch the rich content for the individual Rich Push message. Rich content is served only once for a message, therefore apps must store the rich content upon retrieval.

Message Properties

For each message fetched from Responsys by the SDK, the following message properties are stored in the mobile app's Message Center data store:

Property	Description	Type	Notification action	Required/Optional
`id`	Unique message ID	Text	All	Required
`sent_ts`	Sent timestamp - when the campaign was launched	UTC Time in ISO 8601 format	All	Required
`subject`	Subject line of the message	Text	All	Required
`message`	Push notification text, composed by the Marketer.	Text	All	Required
`deeplink_url`	Deep link destination URL. Set by the Marketer.	URL Encoded	Open URL (Deep link)	Optional
`richmessage_url`	External content URL for Rich Push. Set by the Marketer.	URL Encoded	Open Rich Message (Where rich message content is provided from an external URL)	Optional
`richmessage_html`	External content URL for Rich Push. Set by the Marketer.	Text	Open Rich Message (Where rich message HTML content is selected from the Content Library or entered in the Push Message Designer)	Optional
`icon_url`	Message icon image URL. Set by the Marketer.	URL Encoded	All	Optional
`expiry_ts`	Expiration time stamp for time-sensitive messages. Set by the Marketer in the account’s time zone.	UTC Time in ISO 8601 format	All	Optional
`message_center_name`	Message Center name - Destination message center when an App implements multiple message centers. Defaults to `Primary`.	Text	All	Required

Refer to the platform-specific sections for more information about the data returned for the mobile app SDK calls to the local Message Center data store.

Troubleshooting Message Center

As of the 18B Update and SDK version 6.37.0, the SDK handles any error messages returned when it tries to pre-fetch the Message Center messages from Responsys. Please refer to the platform-specific sections for additional troubleshooting information.

Developing Message Center on Android

This topic describes how to develop Message Center on Android using the Oracle Responsys Mobile App Platform Cloud Service SDK. To understand how the SDK and Responsys support Message Center functionality, see the Message Center topic.

BEFORE YOU BEGIN:

Request access to the Message Center feature by contacting your Customer Success Manager or logging in to My Oracle Support and creating a service request. This feature is currently released under our Controlled Availability program.
Obtain the latest version of the SDK for your supported platforms. All developers working on the mobile app must use the same SDK version (current SDK recommended; minimum SDK 6.39.0 or later).
You must turn on Message Center in your code, using the SDK's setMessageCenterEnabled method. This applies even if you are already using SDK 6.37.0 or later OR are upgrading from an older SDK version to SDK version 6.39.0 or later.

Enabling Message Center

To enable Message Center in an Android app, use the following methods:

PushIOManager.getInstance(this).isMessageCenterEnabled()
PushIOManager.getInstance(this).setMessageCenterEnabled(true)

NOTE: passing false will erase all previously fetched messages.

Data retention policy

The duration Oracle caches Message Center messages is subject to change at anytime. Currently, messages are retained for 15 days from the fetched date, and then they are deleted. Apps should not rely on the SDK cache to act as storage for their app's Message Center messages. Apps must maintain their own storage and be developed to either retain messages for as long as messages are required, or delete messages when no longer needed. Each message has a unique message ID. Apps should check a message's ID to check whether or not the app has already retrieved and stored a message.

Fetching Messages

Messages are pre-fetched (for all Message Centers) when the application is first launched after installation. Thereafter, messages are refreshed at fixed intervals (currently every five minutes). If the mobile app user exits the mobile app, and then re-opens it, the SDK refreshes Message Center messages from Responsys only if it is due for a refresh.

The Push SDK stores retrieved messages locally, and they are served from the local storage on the device to your mobile app on demand.

Once the mobile app fetches a list of messages by calling fetchMessagesForMessageCenter, the app must maintain its own storage for the fetched messages.
Each message has a unique message ID. Apps should check a message's ID to check whether or not the app has already retrieved and stored a specific message.

Fetching Message List

Messages are pre-fetched by the SDK from Responsys and stored locally on the mobile device. When the user opens the Message Center in your mobile app, your mobile app must call the fetchMessagesForMessageCenter method as shown below:

	try {
				PushIOManager.getInstance(this).fetchMessagesForMessageCenter(null, this);
				} catch (PIOMCMessageException e) {
				e.printStackTrace();
		}

Once the mobile app fetches a list of messages by calling fetchMessagesForMessageCenter, the app must maintain its own storage for the fetched messages.

The method takes the following parameters:

messageCenter: message center name. If null, it will fetch the 20 most recent messages from the "Primary" message center.

NOTE: Every Message Center in Responsys is pre-configured with a default message center called Primary. So, unless your marketing team creates new message centers, all messages will be attached to this default message center.
messageListener: Mandatory parameter. The method call is asynchronous and the response is provided in JSON format via a callback through PIOMCMessageListener interface. You need to implement this interface and provide a reference in this parameter.

If the listener parameter is null, an exception is thrown via PIOMCMessageException.

Fetching Rich Content for Message

NOTES:

This SDK feature is available only for PushIO SDK 6.37 or greater.
Apps should retrieve any rich content associated with a message and store the rich content. This rich content is served only once for a message, therefore apps must store the rich content upon retrieval.

While fetchMessagesForMessageCenter() returns a list of messages, if a message has rich content (like HTML), then you need to call the following API to get the rich HTML content:

	try {
				PushIOManager.getInstance(this).fetchRichContentForMessage
				(messageId, new PIOMCRichContentListener() {
				@Override
				public void onSuccess(String messageId, 
				String richContentHtml) { 
				}

				@Override
				public void onFailure(String messageId, 
				PIOMCMessageError piomcMessageError) {
				}
				});
				} catch (PIOMCRichContentException e) {
				e.printStackTrace();
		}

The method takes the following parameters:

messageId: message ID for which the rich content is to be fetched.
richContentListener: The method call is asynchronous and the response is provided via a callback through the PIOMCRichContentListener interface. You need to implement this interface and provide a reference in this parameter. Mandatory parameter.

If the listener parameter is null, a PIOMCRichContentException is thrown.

Listener for New Message Center Messages

Starting with SDK v6.52, your app can listen for new Message Center messages from Responsys.

Following are the steps to get this working,

Add a listener - PIOMessageCenterUpdateListener to get callbacks when your Message Center(s) have new messages.
When this callback is received, the SDK provides a list of Message Center(s) that have been updated.
For each of these Message Center(s), call fetchMessagesForMessageCenter() to get messages for that Message Center.

Following code sample shows the above steps,

                PushIOManager pushIOManager = PushIOManager.getInstance(getApplicationContext());
                pushIOManager.addMessageCenterUpdateListener(new PIOMessageCenterUpdateListener() {
                    @Override
                    public void onUpdate(List<String> messageCenters) {

                        // messageCenters - list of message centers recently updated

                        for(String messageCenter: messageCenters){
                            try {
                                pushIOManager.fetchMessagesForMessageCenter(messageCenter, new PIOMCMessageListener() {
                                    @Override
                                    public void onSuccess(String messageCenter, List<PIOMCMessage> messages) {

                                           // messages - List of messages for this Message Center
                                    }

            						@Override
            						public void onFailure(String messageCenter, PIOMCMessageError messageError) {

            						}
            					});
            				} catch (PIOMCMessageException e) {
            					e.printStackTrace();
            				}
            			}
            		}
		        });

Callbacks and Response

PIOMCMessageListener

In order to receive the messages, you will need to implement PIOMCMessageListener interface and override its methods as follows,

	@Override
				public void onSuccess(String messageCenter, List<PIOMCMessage> messageList) {
				//consume the messages via your own UI.
				}

				@Override
				public void onFailure(String messageCenter, PIOMCMessageError errorReason) {
				//handle failure
		}

A successful operation will return a list of PIOMCMessage. This class is Parcelable, represents a single message, and has getters/setters to access its properties.

PIOMCRichContentListener

In order to receive rich content for a message, you will need to implement the PIOMCRichContentListener interface and override its methods as follows:

	@Override
				public void onSuccess(String messageId, String richContentHtml) {
				//consume the html via your own UI.
				}

				@Override
				public void onFailure(String messageId, PIOMCMessageError errorReason) {
				//handle failure
		}

A successful operation will return a list of PIOMCMessage. This class is Parcelable, represents a single message, and has getters/setters to access its properties.

About the error responses

For various reasons, one of the above method calls might fail, if so, the onFailure method will be called with the reason for this failure. Possible reasons are as follows:

ERROR_EMPTY_RESPONSE: Response payload is empty. Internal error with Responsys API call. This does not imply zero messages.

				ERROR_INVALID_PAYLOAD: Syntactical error in the JSON response.

				ERROR_INVALID_URL: Internal error with Responsys API call.

				ERROR_INVALID_RESPONSE_STATUS: Invalid server response status.

		ERROR_MAX_RETRY_COUNT_REACHED: Request timed out due to the maximum number of retries reached.

App Icon Badges

The Responsys SDK update for 19B includes additional features to support badge count for messages in the message center. It is the responsibility of the app developer to reset the app's badge count on certain actions if required by the app.

App Icon Badges are enabled by default in the SDK. App developers can disable App Icon Badges in the SDK or using the Mobile App Config console.

Prerequisites:

App developers must implement logic to clear the app's badge count before marketers can activate campaigns that alter the badge count for mobile apps. Otherwise your end users' apps will permanently display the Badge Count on the App Icon, resulting in a poor user experience for your app users.
Configure the maximum badge count in the Mobile App Config console. See Configuring Message Centers for more information.

NOTE :

The SDK only supports the following launchers for app icon badges: Sony, Samsung, LG, HTC, Xiaomi, ASUS, ADW, APEX, NOVA, Huawei, ZUK, OPPO, EverythingMe, ZTE, KISS, Launchtime, and Yandex.

As an app developer, there are a few steps you will need to take to fully integrate message center badging into your Android app. We will cover each of these steps in detail:

[1] Enable message center badges

For the SDK to be able to display a badge count for message center on the app icon, the feature needs to be enabled in the application using the API setMessageCenterBadgingEnabled(true). Once enabled, any message center campaigns and push campaigns with a badge count can be shown on the app.

setMessageCenterBadgingEnabled(boolean isBadgingEnabled)
 
Parameter : isBadgingEnabled
			If set to true, badging is enabled; to disable badging, set to false
 
Usage : PushIOManager.getInstance(this).setMessageCenterBadgingEnabled(isChecked);

[2] Set badges locally

The API takes in badgeCount(to be set), a flag to determine if in the event the sync with the server fails, whether or not developers want the SDK to display the badge count on the app icon or not. An optional callback is also available, PIOBadgeSyncListener, which can provide them information of the success or failure of the sync operation.

setBadgeCount(boolean badgeCount,boolean forceSetBadge, PIOBadgeSyncListener badgeSyncListener)
 
Parameters :
badgeCount        //Count to be shown on the app icon, which will then be synced with the server
forceSetBadge    //Flag to determine if the SDK should show the badge count on the app icon, in case there was a server error  
				while syncing this locally set count to the server
badgeSyncListener// This is an optional field, and can be used in case the app developer wants to do extra
				operations on onSuccess or onFailure of this API
 
Usage : PushIOManager.getInstance(this).setBadgeCount(2, true, this);

[3] Reset the badge count

To clear the badge count set on the app icon, use the resetBadgeCount() API. Since this API has to sync the badge count = 0, with the server, the forceSetBadge flag helps the SDK to determine whether or not to clear the badge count if there was a failure while syncing the count.

resetBadgeCount(boolean forceSetBadge, PIOBadgeSyncListener badgeSyncListener)

[4] Get the badge count stored in SDK

The value of the badge count stored in the SDK can be fetched using getBadgeCount() API.

getBadgeCount() returns the badge count as an integer.

Message Center Track Engagements

The Responsys SDK provides APIs to track "Message Display" and "Message Open" engagements for the Message Center.

Message Display engagements should be raised by the app when a Message Center message is displayed to the user in a short/preview format.
Message Open engagements should be raised by the app when the message is displayed in a full/detailed format.

This feature is available on SDK versions 6.45 or later.

[1] Tracking Message Display

When a message preview is displayed to the user (usually as part of a list), you must call trackMessageCenterDisplayEngagement(messageId) for each message. This can be done from within the list's view-adapter, as shown below.

public class MessageListAdapter extends RecyclerView.Adapter<MessageItemViewHolder> {

				@Override
				public void onBindViewHolder(MessageItemViewHolder viewHolder, int i) {
				PIOMCMessage message = mItemList.get(i);
				PushIOManager.getInstance(mActivity).trackMessageCenterDisplayEngagement(message.getId());
				}

				@Override
				public int getItemCount() {
				return mItemList.size();
				}

				public List<PIOMCMessage> getItems() {
				return mItemList;
				}
				}

This example references a RecyclerView. If you use a different view to display the messages, find the appropriate location where each item view is created to place the API call.

NOTE :

trackMessageCenterDisplayEngagement() API call is asynchronous. So, it does not affect the performance of the View.
The messageId passed with trackMessageCenterDisplayEngagement() is filtered for uniqueness. So, calling the API multiple times with the same message ID in one session will not result in multiple message-display engagements being reported for that message.
For tracking the Message Display engagement, it is important to define a Message Center session using onMessageCenterViewVisible() and onMessageCenterViewFinished().

These methods should be called from your Message Center Activity/Fragment lifecycle methods (onStart() and onStop() or other lifecycle methods depending on your specific use-case).

@Override
protected void onStart() {
	super.onStart();
	try {
		PushIOManager.getInstance(getApplicationContext()).onMessageCenterViewVisible();
	} catch (PIOMCMessageException e) {
		// handle this Exception
		}
}

@Override
protected void onStop() {
	super.onStop();
	try {
		PushIOManager.getInstance(getApplicationContext()).onMessageCenterViewFinished();
	} catch (PIOMCMessageException e) {
		// handle this Exception
	}
}

NOTE : If the session APIs are incorrectly called, the SDK will throw a PIOMCMessageException exception.

[2] Tracking Message Opens

When a Message Center message is displayed in a detail-view, you should call trackMessageCenterOpenEngagement(messageId) to record the engagement.

This API call is not bound to a session and should be called whenever the user opens a particular message.

PushIOManager.getInstance(getContext()).trackMessageCenterOpenEngagement(message.getId());