Rich Push Client Library - iOS¶
Overview¶
Urban Airship’s Rich Push gives you a drop-in user interface that provides push notification persistence and rich messaging through a persistent inbox.
The Rich Push inbox is a reference implementation of the Rich Push API.
Download¶
Rich Push inbox is available in two parts: a static library and an optional sample implementation.
We recommend everyone download the latest stable version.
Libary: http://com.urbanairship.filereleases.s3.amazonaws.com/libUAirship-latest.zip
Sample App: http://com.urbanairship.filereleases.s3.amazonaws.com/RichPushSample-latest.zip
If you’re feeling brave you can download the latest development version of all our iOS code or you can check the code out with git:
git clone git://github.com/urbanairship/ios-library.git
The library and sample app are completely open source, so you may modify them as you wish. Patches and pull requests are always welcome.
Upgrade from a Previous Version¶
If you are currently using a 1.4.x or earlier version of the previously named “AirMail Inbox” sample application, there are several changes you must make to your application in order to upgrade. The first step is to make a back-up of your current project. Once your project has been backed up, you’ll remove the old Urban Airship code, install the new code and make some simple changes to the project and your application.
Install libUAirship¶
First, delete the Airship directory from your current project. Ensure that you delete the files from the disk and not just the project references. Next, download and unzip the latest version of libUAirship. Copy the Airship directory into your project folder:
cp -r Airship /SomeDirectory/YourProject/
Now inside of Xcode, import the source files into your project.
Update your Project Target¶
Rich Push inbox requires that you link your application against some additional frameworks:
libUAirship.a (Add Other, then locate "libUAirship-1.0.0.a" in the Airship directory)
CoreTelephony (Exists in iOS 4.x only, so make it a weak link for 3.x compatibility)
StoreKit
You may need to make some other changes to your project. See Build Settings for details.
Update Code References¶
All Urban Airship classes are now prefixed with “UA”. You will need to update any imports and references to the old classes and headers.
Relevant changes include:
- Airship is now UAirship
- Airmail is now UAInbox
- AirMailPushHandler is now UAInboxPushHandler
- AirMailInboxObserver functionality is now defined in UAMessageListObserver
- AirMailDelegate functionality is now defined in UAInboxUIProtocol
Update Airship Integration¶
Recommended changes to your app delegate in applicationDidFinishLaunching:withOptions
Set the UI class (do this first):
//Set custom UI
[UAInbox useCustomUI:[UAInboxUI class]];
The takeOff method now takes a NSDictionary of configurable options:
//Init Airship launch options
NSMutableDictionary *takeOffOptions = [[[NSMutableDictionary alloc] init] autorelease];
[takeOffOptions setValue:launchOptions forKey:UAirshipTakeOffOptionsLaunchOptionsKey];
// To use your own pre-existing inbox credentials, uncomment and modify these lines:
//[takeOffOptions setValue:@"4cf54407a9ee256d9400000c" forKey:UAAirshipTakeOffOptionsDefaultUsername];
//[takeOffOptions setValue:@"GUvTvih4RcaqZZOAsLvKXQ" forKey:UAAirshipTakeOffOptionsDefaultPassword];
// Create Airship singleton that's used to talk to Urban Airship servers.
// Please populate AirshipConfig.plist with your info from http://go.urbanairship.com
[UAirship takeOff:takeOffOptions];
The push handler is now UI-independent, so you must now specify a view controller that you want to act as the Inbox parent (it will display as a modal by default):
[UAInboxUI shared].inboxParentController = viewController;
[UAInboxPushHandler handleLaunchOptions:launchOptions];
if ([[UAInbox shared].pushHandler hasLaunchMessage]) {
[UAInboxUI loadLaunchMessage];
}
Changes to applicationDidBecomeActive:
Add the following lines, replacing [AirMailPushHandler cacelPreviousAlertAndShowMessage] if it is present:
id<UAInboxAlertProtocol> alertHandler = [UAInboxUI getAlertHandler];
[alertHandler cancelPreviousAlertAndShowMessage];
To display the Inbox (eg, from a view controller), call:
[UAInbox displayInbox:parentViewController animated:YES];
Update your Custom UI¶
If you are using a custom UI, you will need to and is now defined by the following protocols:
UAInboxUIProtocol
UAInboxAlertProtocol
UAInboxMessageListObserver
Example implementations of these protocols can be found in the Inbox sample application.
Other Upgrade Notes¶
The username and password are now stored in the device keychain. It will be moved automatically by the new library. The only functional difference is that the username and password can be retrieved by the application even if it is uninstalled and then subsequently reinstalled.
Set Up a New Application¶
Copy libUAirship Files¶
Download and unzip the latest version of libUAirship. Copy the Airship directory into the same directory as your project:
cp -r Airship /SomeDirectory/ (where /SomeDirectory/YourProject/ is your project)
If you are not using the sample project, you’ll need to import the source files into your project.
Required Libraries¶
Rich Push requires your application to link against the following Frameworks:
libUAirship-<version>.a
CFNetwork.framework
CoreGraphics.framework
Foundation.framework
MobileCoreServices.framework
Security.framework
SystemConfiguration.framework
UIKit.framework
libz.dylib
libsqlite3.dylib
CoreTelephony.framework (this is iOS 4.x+ only, so make it a weak link for 3.x support)
StoreKit.framework
Build Settings¶
Compiler
Your project should use the GCC compiler (the default). LLVM is not supported at this time.
Header search path
Ensure that your build target’s header search path includes the Airship directory.
Linker
In order to properly link against the Urban Airship static library, you will need to set the -all_load flag in your build target’s Other Linker Flags.
Key Files¶
There are only a handful of files you’ll need to know to get started as a developer.
UAInbox¶
The actual inbox object. This object provides the primary interface for interacting with the UI, including methods for displaying and hiding the inbox.
UAInboxPushHandler¶
This class handles incoming push notifications, displaying those notifications to the user and then opening the message if the user clicks ‘View’. This class has two key methods handleNotification:forInbox: and handleLaunchOptions: The handleNotification:forInbox: method handles notifications while your app is running. It takes the NSDictionary reference received from application:didReceiveRemoteNotification:, and the user’s inbox. The handleLaunchOptions: method handles notifications received from outside the application, and takes the NSDictionary received from application:didFinishLaunchingWithOptions.
UAMessageListObserver¶
This is a protocol your objects can implement in order to receive notices of basic inbox actions. Once you’ve implemented the interface just add your class as an observer to the active inbox.
UAInboxUIProtocol¶
This is a protocol that defines the UI interactions for the inbox. UAInboxUI is an example implementation provided in the sample project.
Quickstart¶
Prerequisite¶
Before getting started you must perform the steps above outlined in Set Up a New Application.
In addition you’ll need to include UAirship.h and UAInbox.h in your source files. If you are using the sample UI, you’ll need to include UAInboxUI.h.
Airship API Setup¶
Inside your application delegate’s application:didFinishLaunchingWithOptions: method initialize a shared UAirship instance replacing YOUR APP KEY and YOUR APP SECRET with the keys provided on the Urban Airship web dashboard. Do not use the Master Secret.
If you create the inbox via the Rich Push API you can explicitly initialize the application for use with that inbox by uncommenting the relevant lines and setting the username and password.
//Init Airship launch options
NSMutableDictionary *takeOffOptions = [[[NSMutableDictionary alloc] init] autorelease];
[takeOffOptions setValue:launchOptions forKey:UAirshipTakeOffOptionsLaunchOptionsKey];
// To use your own pre-existing inbox credentials, uncomment and modify these lines:
//[takeOffOptions setValue:@"4cf54407a9ee256d9400000c" forKey:UAAirshipTakeOffOptionsDefaultUsername];//username
//[takeOffOptions setValue:@"GUvTvih4RcaqZZOAsLvKXQ" forKey:UAAirshipTakeOffOptionsDefaultPassword];//password
// Create Airship singleton that's used to talk to Urban Airhship servers.
// Please replace these with your info from http://go.urbanairship.com
[UAirship takeOff: @"YOUR_APP_KEY" identifiedBy: @"YOUR_APP_SECRET" withOptions:takeOffOptions];
You will also need to init the UI and start it if the app launched from a push:
//Init the UI
[UAInbox useCustomUI:[UAInboxUI class]];//sample UI implementation
// If the application gets an UAInbox message id on launch open it up immediately.
// Only works for the default inbox
[UAInboxUI shared].inboxParentController = viewController;
[UAInboxPushHandler handleLaunchOptions:launchOptions];
if ([[UAInbox shared].pushHandler hasLaunchMessage]) {
[UAInboxUI loadLaunchMessage];
}
Register for Push Notifications¶
Register for push notifications in application:didFinishLaunchingWithOptions:
// Register for notifications
[[UIApplication sharedApplication]
registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge |
UIRemoteNotificationTypeSound |
UIRemoteNotificationTypeAlert)];
Then, implement the callback that registers your new device token with Urban Airship:
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
// Updates the device token and registers the token with UA
[[UAirship shared] registerDeviceToken:deviceToken];
}
Launch Rich Push to an inbox¶
Displaying the inbox is as simple as making a single call and passing in the view controller from which you wish to launch the Inbox UI.
[UAInbox displayInbox:parentViewController animated:YES];
Opening incoming push notifications¶
You can send along Push notifications along with your Rich Push. These notifications will be associated with an Rich Push Inbox ID and on receipt the user can choose to ‘View’ the message. In this case we allow you to check for the incoming ID and view the message directly.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
[UAInboxPushHandler handleLaunchOptions:launchOptions];
...
}
Badge Updates¶
Rich Push inbox handles updating your application’s badge number when new messages are sent and then again once messages are read so you don’t have to worry about keeping track of them. Therefore we don’t recommend setting the badge number manually via Push notification since Rich Pushes will override it.
The Sample User Interface¶
When a user launches a Rich Push enabled app, the first thing they will see is the Inbox screen. This screen displays the list of messages that the user has in his or her inbox, as well as whether or not they have been read. The number of unread messages is indicated by the badge in the title. To delete a message, the user can swipe it. The user can mark any number of messages as read, or delete them, by clicking the Edit button. By clicking on any of the messages, the user will be taken to the Message Detail screen.
Once a user has selected a message to view, that message is loaded from Urban Airship servers. The message will then be marked as viewed on our servers. The message is rendered in a UIWebView, so your messages can contain full HTML, CSS and Javascript, including mobile Safari features like client side SQL storage and geolocation.
You can also use Rich Push for your iPad apps. The Rich Push default user interface takes advantage of the iPad’s larger size, and displays the Inbox and Message Detail screens together in split-screen.
Localization¶
The Rich Push sample has built-in localization support and provides English and Chinese translations. All Urban Airship localization strings for Rich Push are contained in their own bundle:
UAInboxLocalization.bundle
To add a new translation just copy one of the existing lproj directories into the bundle and update all of the items in Localizable.strings
Sending Rich Pushes from the Urban Airship Dashboard¶
To send test or broadcast Rich Push messages log into: https://go.urbanairship.com
Once you’ve navigated to your application’s detail page, click on the Rich Push option, then on Test Rich Push Messages menu option in the side menu.
The test message form has several options that allow you to specify the message contents and optionally a push notification to be sent along with the message. The message body can contain html, css and javascript.
