Message Center

The default Message Center is provided out of the box to all customers using iOS or Android SDK 7.0.0 or later. It requires little to no integration to get started and supports some basic theming options.

This guide covers the various tools available for creating custom Message Center implementations, starting with the simplest and moving on to more advanced use cases.

Displaying the Default Message Center

By default, when the app receives a push notification carrying a Message Center Action, the Message Center will be automatically displayed in a modal view controller.

The default Message Center can also be displayed manually with a simple method call on the UAMessageCenter instance. By wiring this method call to a button in your app, you can quickly produce a user-initiated Message Center with no additional effort.

Displaying the Message Center
UAirship.messageCenter().display()
[[UAirship messageCenter] display];

Adding a Custom Look and Feel

The default implementation displays with default settings for elements such as colors, fonts, and title text. In the following section we'll explore ways to customize its look and feel without having to create custom UI.

Most developers will want to customize the look and feel to match their app's existing style and layout. By setting a handful of top-level properties for the default Message Center you can override the default style to quickly arrive at a look and feel matching that of your app. We'll cover a few of these to show how easy this process can be.

Title

A good place to start is the title property on UADefaultMessageCenter . This is the title text that displays in the navigation bar above the message list. By default, the title is a localized string reading "Message Center", but it can be overridden by setting the property directly.

UAirship.defaultMessageCenter().title = "My Message Center"
[UAirship defaultMessageCenter].title = @"My Message Center";

Styling the Message Center

The default message center's look can be customized by creating a UAMessageCenterStyle instance, setting its style properties, and then setting the style property of the Message Center instance to the customized style instance.

For instance, we may want to change the color of the navigation bar in order to match our app and set custom fonts for the title and table view cells. In the example below, we assume the app has access to the "Roboto" font, but any stock or custom font may be used.

Styling the Message Center
let style = UAMessageCenterStyle()

// Customize the style object
style.navigationBarColor = UIColor(red: 0.988, green: 0.694, blue: 0.106, alpha: 1)
style.titleColor = UIColor(red: 0.039, green: 0.341, blue: 0.490, alpha: 1)
style.tintColor = UIColor(red: 0.039, green: 0.341, blue: 0.490, alpha: 1)

style.titleFont = UIFont(name: "Roboto-Regular", size: 17.0)
style.cellTitleFont = UIFont(name: "Roboto-Bold", size: 14.0)
style.cellDateFont = UIFont(name: "Roboto-Light", size: 12.0)

// Set the style
UAirship.messageCenter().style = style
UAMessageCenterStyle *style = [UAMessageCenterStyle style];

// Customize the style object
style.navigationBarColor = [UIColor colorWithRed:0.988 green:0.694 blue:0.106 alpha:1];
style.titleColor = [UIColor colorWithRed:0.039 green:0.341 blue:0.490 alpha:1];
style.tintColor = [UIColor colorWithRed:0.039 green:0.341 blue:0.490 alpha:1];

style.titleFont = [UIFont fontWithName:@"Roboto-Regular" size:17.0];
style.cellTitleFont = [UIFont fontWithName:@"Roboto-Bold" size:13.0];
style.cellDateFont = [UIFont fontWithName:@"Roboto-Light" size:12.0];

// Set the style
[UAirship messageCenter].style = style;

This can also be done without writing code by creating a plist file. Create a plist with the desired message center style. All the keys correspond to properties on the UAMessageCenterStyle class. Save the plist and include it in the application's target. Then, update messageCenterStyleConfig with the name of the plist file.

Styling the Message Center using a plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>titleFont</key>
        <dict>
                <key>fontName</key>
                <string>Roboto-Regular</string>
                <key>fontSize</key>
                <string>17</string>
        </dict>
        <key>titleColor</key>
        <string>#00698f</string>
        <key>tintColor</key>
        <string>#00698f</string>
        <key>navigationBarColor</key>
        <string>#eaaa00</string>
        <key>iconsEnabled</key>
        <false/>
        <key>cellTitleFont</key>
        <dict>
                <key>fontName</key>
                <string>Roboto-Bold</string>
                <key>fontSize</key>
                <string>13</string>
        </dict>
        <key>cellDateFont</key>
        <dict>
                <key>fontName</key>
                <string>Roboto-Light</string>
                <key>fontSize</key>
                <string>17</string>
        </dict>
</dict>
</plist>

Message Center Filtering

Sometimes it can be useful to filter the contents of the message center according to some predetermined pattern. To facilitate this, use the UAMessageCenter filter property to set a predicate. Once set, only messages that match the predicate will be displayed. As a simple example, the filter shown keeps only messages whose titles contain the string "Cool".

Filtering messages
UAirship.defaultMessageCenter().filter = NSPredicate { (evaluatedObject, _) in
     let message = evaluatedObject as! UAInboxMessage
     let titleString:NSString = message.title as NSString
     return titleString.contains("Cool")
 };
[UAirship defaultMessageCenter].filter = [NSPredicate predicateWithBlock:^BOOL(id evaluatedObject, NSDictionary *bindings) {
    UAInboxMessage *message = (UAInboxMessage *)evaluatedObject;
    return [message.title containsString:@"Cool"];
}];

Overriding the default Message Center

For custom Message Center implementations, initialize the UAInboxDelegate with the custom Message Center implementation's view controller. This is necessary to ensure that the default modal Message Center is not displayed on top of the custom Message Center when a message is received.

Overriding the default Message Center
self.inboxDelegate = CustomInboxDelegate()
UAirship.inbox().delegate = self.inboxDelegate
self.inboxDelegate = [[CustomInboxDelegate alloc] init];
[UAirship inbox].delegate = self.inboxDelegate;

Badge Updates

The value of the badge can be set in a number of ways. Most often, the number corresponds with some notion of unread or unviewed content, e.g., email messages or friend requests. The most common way to update the badge is directly through APNS, either by passing along the badge integer in the payload of a push notification, or by telling the app to adjust the value using our autobadge feature.

For applications implementing the Message Center, you may want the badge value to represent the actual state of unread messages in the Message Center. If so, then you need to set this behavior in the application delegate.

Updating badge value to message center unread count
func applicationWillResignActive(application: UIApplication) {
    if (UAirship.inbox().messageList.unreadCount >= 0) {
        application.applicationIconBadgeNumber = UAirship.inbox().messageList.unreadCount
    }
}
- (void)applicationWillResignActive:(UIApplication *)application {
    if ([UAirship inbox].messageList.unreadCount >= 0) {
        application.applicationIconBadgeNumber = [UAirship inbox].messageList.unreadCount;
    }
}

If you use this method then you should never include badge values in the payload of push notifications, because Message Center will override them.

App Transport Security

Message Center content features such as Landing Pages are only able to load SSL-encrypted web content out of the box. This iOS feature, known as App Transport Security, requires all web connections to use SSL, and only allows for whitelisting exceptions on an individual basis. Content hosted on Urban Airship's servers is already SSL-encrypted, but if you plan to use your own content, you will need to make sure it is accessible behind SSL so that iOS will not prevent the SDK from loading it. While we generally recommend leaving these default settings alone, if your app will need to load plain HTTP content then you can whitelist individual domains in your app's Info.plist file. For more information, see Apple's App Transport Security Technote.

Advanced Uses

Advanced Styles

If your app has the ability to send list icons, these can be enabled by setting a single Boolean parameter.

style.isIconsEnabled = true
style.iconsEnabled = YES;

Localization

The default Message Center uses string resources to localize its UI. Ordinarily the SDK will read a file named UAMessageCenterUI.strings in the AirshipResources bundle. However, you can override this by adding your own versions of the file to the main bundle of your app. The SDK will search here first, falling back on AirshipResources as necessary.

At present, the strings available for localization are as follows.

"UA_Message_Center_Title" = "Message Center";

"UA_Message" = "Message";

"UA_OK" = "OK";
"UA_Retry" = "Retry";
"UA_Cancel" = "Cancel";

"UA_Loading" = "Updating";
"UA_No_Messages" = "No Messages";
"UA_No_Message_Selected" = "No Message Selected";

"UA_Select_All" = "Select All";
"UA_Select_None" = "Select None";

"UA_Delete" = "Delete";
"UA_Mark_as_Read" = "Mark Read";

"UA_Error_Connection" = "Connection Error";
"UA_Error_Loading_Message" = "Unable to load message. Please try again later.";
"UA_Error_Loading_Message_List" = "Unable to load messages. Please try again later.";


A Deeper Look

While the default Message Center is ideal for many use cases, there may be times when it's more appropriate to embed a Message Center in a specific location within your app. While the default Message Center attempts to strike a balance between configurability and hassle-free implementation, some implementation decisions can only be made on a case-by-case basis, such as placement and navigation.

In this section we'll cover some key classes that are useful for creating custom implementations, and walk through one that embeds a Message Center in a tab. Though we won't be using the default Message Center as such, we can still use the UI classes it depends on. These can all be styled using the same UADefaultMessageCenterStyle class covered in the section above, allowing for more rapid development.

Library Components

Custom Message Center implementations will depend on at least some combination of the classes and protocols described below. For additional detail, please see the Urban Airship Library Reference.

UAInbox

UAInbox is the main entry point for fetching and accessing messages, as well as signing up for delegate callbacks.

UAInboxMessageList

UAInboxMessageList provides an interface for retrieving messages asynchronously, as well as a reference to the local message array itself. For instance, the example below shows how to retrieve new messages remotely:

UAirship.inbox().messageList.retrieveMessageList(successBlock: {
   // handle success
}, withFailureBlock: {
    // handle failure
})
[[UAirship inbox].messageList retrieveMessageListWithSuccessBlock:^{
    // handle success
} withFailureBlock:^{
    // handle failure
}];


If you are using or subclassing the default UI classes, this operation shouldn't ordinarily be necessary. On the other hand, if you are designing custom UI, you can use the above call to implement refresh behavior. Accessing the local array of messages is straightforward:

let messages = UAirship.inbox().messageList.messages
NSArray *messages = [UAirship inbox].messageList.messages;


Note

The message list uses CoreData under the hood, and as such the message objects contained within are ephemeral references, refreshed along with the list after retrieval. It is not recommended to hold onto individual instances indefinitely.

UAInboxMessage

UAInboxMessage is the model object representing an individual message available for display. Instances of this class do not contain the actual message body. Rather, they point to the URL corresponding to the message body in the backend. These URLs are authenticated using UAUser credentials. Normally the default UI will handle most details involving message display transparently, but deep customizations ultimately involve displaying these URLs in a webview.

UAInboxDelegate

UAInboxDelegate is a protocol that can be used to sign up for delegate callbacks when messages are available for viewing, or when UI should be shown. This can be useful in custom implementations that embed or subclass the default UI, as your app can use these events to navigate to the appropriate location when a new message (or the entire Message Center) needs to be displayed.

To register for callbacks, simply assign a delegate to UAInbox :

UAirship.inbox().delegate = myDelegate
[UAirship inbox].delegate = myDelegate;


In the following sections we'll walk through a custom implementation that uses this feature in more detail.

UAWebViewDelegate or UAWKWebViewNativeBridge

Most Message Center messages are rich HTML pages displayed in a web view. Our default UI classes can handle the details of web view presentation for you, but you can instruct these classes to use either UIWebView or WKWebView using the useWKWebView flag in AirshipConfig.plist. If you need to create a custom implementation with your own webview, UAWebViewDelegate (UIWebView) or UAWKWebViewNativeBridge (WKWebView) can be used to simplify integration with Urban Airship features such as the Actions Framework.

Note

UIWebView support will be removed from our default UI classes in iOS SDK 9.0.

Embedding the Message Center UI

Prior to Urban Airship SDK 7.0.0, all Message Center implementations were effectively custom jobs and involved either a complete implementation from scratch or heavily modified sample code and resources. These approaches are still available when the situation is warranted, but for common use cases it is much easier to reuse pieces of the default UI.

In this example we'll be subclassing UADefaultMessageCenterSplitViewController .

import AirshipKit

class MessageCenterViewController : UADefaultMessageCenterSplitViewController {

}
#import <AirshipKit/AirshipKit.h>

@interface MessageCenterViewController : UADefaultMessageCenterSplitViewController
@end
Assign a Custom Style

As a starting point, we can override the viewDidLoad method to assign a custom style to the view controller as we did above to the default Message Center.

override func viewDidLoad() {
     super.viewDidLoad()

     let style = UADefaultMessageCenterStyle()

     let robotoLight = UIFont(name: "Roboto-Light", size: 12.0)
     let robotoBold = UIFont(name: "Roboto-Bold", size: 14.0)
     let robotoRegular = UIFont(name: "Roboto-Regular", size: 17.0)

     style.navigationBarColor = UIColor(red: 0.988, green: 0.694, blue: 0.106, alpha: 1)
     style.titleColor = UIColor(red: 0.039, green: 0.341, blue: 0.490, alpha: 1)
     style.tintColor = UIColor(red: 0.039, green: 0.341, blue: 0.490, alpha: 1)

     style.titleFont = robotoRegular
     style.cellTitleFont = robotoBold
     style.cellDateFont = robotoLight

     self.style = style
 }
- (void)viewDidLoad {
    [super viewDidLoad];

    UADefaultMessageCenterStyle *style = [UADefaultMessageCenterStyle style];

    UIFont *robotoLight = [UIFont fontWithName:@"Roboto-Light" size:12.0];
    UIFont *robotoBold = [UIFont fontWithName:@"Roboto-Bold" size:13.0];
    UIFont *robotoRegular = [UIFont fontWithName:@"Roboto-Regular" size:17.0];

    style.navigationBarColor = [UIColor colorWithRed:0.988 green:0.694 blue:0.106 alpha:1];
    style.titleColor = [UIColor colorWithRed:0.039 green:0.341 blue:0.490 alpha:1];
    style.tintColor = [UIColor colorWithRed:0.039 green:0.341 blue:0.490 alpha:1];

    style.titleFont = robotoRegular;
    style.cellTitleFont = robotoBold;
    style.cellDateFont = robotoLight;

    self.style = style;
}
Display a Specific Message

Next we'll add a method that allows code from the outside to display a specific message upon request. This will help with the creation of the UAInboxDelegate in the next section. It also happens to be rather easy when using the default UI classes, as demonstrated below.

func displayMessage(message: UAInboxMessage) {
    self.listViewController.displayMessage(message)
}
- (void)displayMessage:(UAInboxMessage *)message {
    [self.listViewController displayMessage:message];
}


Creating and Registering a Custom Inbox Delegate

Implementing the UAInboxDelegate protocol gives your app the chance to respond to events regarding Message Center display, or the display of individual messages within your Message Center. As this is an optional protocol, it also has the effect of overriding the default Message Center implementation.

When the Urban Airship SDK receives a Message Center action, the first thing it does is check whether an inbox delegate has been set. If not, the SDK will use the default Message Center. Otherwise it will delegate that responsibility to your app.

Create the Delegate

First, let's create the delegate class. The structure of the class and design patterns used within are a matter of preference, but for an app built around a tab bar controller, one straightforward approach is to initialize it with the root view controller and use that at runtime to navigate to the appropriate tab when necessary.

import AirshipKit

class InboxDelegate : NSObject, UAInboxDelegate {

    var rootViewController : UIViewController

    init(rootViewController:UIViewController) {
        self.rootViewController = rootViewController
    }

    func messageViewController() -> MessageCenterViewController {
        let tabBarController = self.rootViewController as! UITabBarController
        let viewController = tabBarController.viewControllers![2]
        return viewController as! MessageCenterViewController
    }

    func showInbox() {
        let tabBarController = self.rootViewController as! UITabBarController
        tabBarController.selectedIndex = 2
    }

    func showInboxMessage(message: UAInboxMessage) {
        self.showInbox()
        self.messageViewController().displayMessage(message)
    }
}
#import "InboxDelegate.h"
#import "MessageCenterViewController.h"

@interface InboxDelegate ()
@property(nonatomic, strong) UIViewController *rootViewController;
@end

@implementation InboxDelegate

- (instancetype)initWithRootViewController:(UIViewController *)rootViewController {
    self = [super init];
    if (self) {
        self.rootViewController = rootViewController;
    }
    return self;
}

- (MessageCenterViewController *)messageCenterViewController {
    UITabBarController *tabBarController = (UITabBarController *)self.rootViewController;
    return [tabBarController.viewControllers objectAtIndex:2];
}

- (void)showInboxMessage:(UAInboxMessage *)message {
    [self showInbox];
    [[self messageCenterViewController] displayMessage:message];
}

- (void)showInbox {
    UITabBarController *tabBarController = (UITabBarController *)self.rootViewController;
    tabBarController.selectedIndex = 2;
}

@end


Keep in mind that the index of 2 used above assumes that the MessageCenterController occupies the third tab in the application. Regardless of the implementation details, the fundamental approach remains the same, which is that the delegate is responsible for handling showInbox and showInboxMessage events, and navigating to the tab containing the MessageCenter when needed.

Register the Delegate

Next, in order for the InboxDelegate to actually receive those events, it must be registered. An easy place to do this would be in the AppDelegate, after takeOff.

func applicationDidFinishLaunching(_ application: UIApplication) {

    // ...

    // Set a custom delegate for handling Message Center events
    self.inboxDelegate = InboxDelegate(rootViewController: (window?.rootViewController)!)
    UAirship.inbox().delegate = self.inboxDelegate

    // ...
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...

    // Set a custom delegate for handling Message Center events
    self.inboxDelegate = [[InboxDelegate alloc] initWithRootViewController:self.window.rootViewController];
    [UAirship inbox].delegate = self.inboxDelegate;

    // ...
}


With these pieces in place, your embedded Message Center should be ready for use.