Message Center

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.

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. At runtime, Responsys and the mobile app interact 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

[1.] The Responsys Integrated Push customer decides to implement Message Center and submits a service request to Oracle Support.

[2.] Oracle enables the customer’s Responsys account for Message Center.

[3.] Mobile App Developers create the user experience in their mobile app, with input from the Marketing team.

[4.] 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.)

[5.] 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. For a Message Center campaign, campaign messages are available to the mobile apps but a Push notification is not sent to mobile app users.

Runtime

[1.] 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.

[2.] If the Message Center message is part of a Push campaign, mobile app users receive the Push notification.

[3.] 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 all non-expired messages 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.

[5.] The mobile app user access the Message Center in the mobile app.

[6.] 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.

[7.] The mobile app user sees the messages listed in the mobile app’s Message Center.

[8.] 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 to the app user the number of new Message Center messages available. Marketers can increment, specify a value for, or clear the Badge Count for every message sent to user's device. App Icon Badging with Message Center Messages can drive increased 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 is 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 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 all non-expired Message Center messages for each Message Center configured for the app, for 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 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.

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.

Platform-specific topics

To enable Message Center in your mobile app code, refer to the platform-specific topics: