Oracle Help Center | Oracle Responsys Mobile App Platform Cloud Service title

Message Center on Android

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:

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 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.

Fetching Messages

The Oracle Responsys Mobile App Cloud Platform SDK (Push SDK version 6.37.0 onwards) retrieves "Message Center" messages from Responsys at fixed intervals every time a mobile app is launched. The Push SDK stores retrieved messages locally, and they are served from the local storage on the device to your mobile app on demand.

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: 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. Mandatory parameter.

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

Fetching Rich Content for Message

NOTES:

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.

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:

NOTE :

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.