This topic describes how to develop Message Center on iOS 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.
To enable Message Center in an iOS app, use the following methods:
[[PushIOManager sharedInstance] isMessageCenterEnabled];
NOwill remove all previously fetched messages.
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.
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.
PIOMCMessageinstances, which can be iterated through to get the details of each message. (To use
PIOMCMessage, you must import
fetchMessagesForMessageCentercall is fetching messages from SDK 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.
Example - Fetching messages:
PIOMCMessage, add the following:
PIOMCMessage is a model class contains the following properties of messages:
messageID: String value containing message's unique identifier.
subject: String value containing message's subject.
message: String value containing message.
iconURL: String value containing message's icon URL.
messageCenterName: String value containing message's message center name.
deeplinkURL: String value containing message's deep link URL.
richMessageHTML: String value containing message's rich message HTML.
richMessageURL: String value containing message's rich message URL.
sentTimestamp: NSDate value containing the message sent date and time.
expiryTimestamp: NSDate value containing the message expiry date and time.
Different error types are returned to determine the different types of failures.
PIOErrorCodeNoNetwork: No network available while trying to fetch the messages.
PIOErrorCodeMaximumRetryReached: Maximum retrial tried to fetch the messages.
PIOErrorCodeInvalidURL: Invalid URL formed(can occur if app tries to fetch messages without SDK configured).
PIOErrorCodeInvalidPayload: Invalid fetch message response received from server.
PIOErrorCodeEmptyResponse: Empty response received while trying to fetch messages.
PIOHTTTPStatusCodeInvalidAppOrAccountToken: AppToken or AccountToken is invalid/not recognized by server.
PIOHTTTPStatusCodeMCDisabled: Given MessageCenter name is disabled in server.
PIOHTTTPStatusCodeMCFailure: Failed to fetch messages for provided message center name.
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.
fetchRichContent as follows:
This SDK feature is available only for PushIO SDK 6.37 or greater.
Rich content can only be requested once for a message. Your mobile application must store the received rich content for further use.
NOTE: The SDK makes the server request to fetch messages for all inboxes internally. So listening for the raw response in application may not provide business value for the application. Be careful if application needs to use the received raw response.
If desired, your mobile application can capture the raw messages (JSON) response received from Responsys:
[1.] Put an observer for notification constant
[2.] Fetch the message response from notification's
PIOMCRawResponseValue) and convert it into a string to use:
The Responsys SDK update for 19B includes additional features to support badge count for messages in the message center. Badging is enabled by default in the SDK. It is the responsibility of the app developer to reset the app's badge count on certain actions if required by the app.
App developers must implement logic to clear the app's badge count before marketers can activate campaigns that increment 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.
The Responsys iOS SDK provides the following APIs to manage this functionality from the app.
 Set badge count from app
Typically the badge count is set by the server. But in certain cases, the badge count needs to be set explicitly. Use
setBadgeCount API to set the badge count of app which will also sync this badge count value with the Responsys server.
If an error occurs while syncing the badge count to the Responsys platform server, an error will be returned in the completion handler and the badge count will not be set.
NOTE: When setting the badge count, the value cannot be less than 0. The badge count value of 0 clears the badge icon for the app.
 Reset the badge count
Use this API to reset and clear the badge count from the app icon. This API syncs the badge count value 0 with the server. If an error occurs while syncing the badge count to the Responsys platform server, an error will be returned in the completion handler and the app badge count will not be cleared.
NOTE: Using this API or setting the badge count to 0 will also clear the App notifications from the notification center.
 Get the badge count for the App
This API will return the current value of the app badge count.
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.
 Tracking Message Display
When a message preview is displayed to the user (usually as part of a list), you must call
trackMessageCenterDisplayEngagement: with a
messageId for each message. You can call this API from
UICollectionView datasource or any other custom view. The following example uses
This example uses the
UITableView datasource. 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.
trackMessageCenterDisplayEngagement() API call is asynchronous. So, it does not affect the performance of the View.
messageId passed with
trackMessageCenterDisplayEngagement is filtered for uniqueness. If this API is called multiple times with the same
messageId in one session, it will not result in multiple Message Display engagements reported for that message.
For tracking the Message Display engagement, it is important to define a Message Center session using
These methods should be called from
UIViewController of your Message Center ViewController where these messages are being displayed. You should call these methods in
UIViewController lifecycle (
viewWillDisappear or other lifecycle methods depending on your specific use case).
messageCenterViewWillDisappear is responsible to flush these events to responsys server and will end the session.
 Tracking Message Opens
When a Message Center message is displayed in a detail view, you should call
trackMessageCenterOpenEngagement: to record the engagement.
This API call is not bound to a session and should be called whenever the user opens a particular message.