UrbanAirship - Push notifications

This article describes how to prepare a mobile app to receive push notifications from the Rubiq Platform.

The Rubiq Platform uses UrbanAirship as a push notification provider. In order to enable push notifications using UrbanAirship:

1. Rubiq needs to know the UrbanAirship MasterKey and AppKey, which can be accessed from the UrbanAirship App dashboard.
2. The UrbanAirship SDK must be integrated into the mobile app
3. The UrbanAirship device ChannelID must be registered with the Rubiq Platform

dialogportal™ Push Activities will then be able to generate push notifications, sending them to UrbanAirship using the registered device ChannelIDs, and UrbanAirship can then deliver the notifications to the devices.

This document focuses on iOS apps, but most of the concepts apply equally to Android apps.

UrbanAirship mobile app registration

The UrbanAirship SDK can be integrated using various methods e.g. Cocoapods, classic etc. The exact steps to setup the SDK are specified in detail on the website http://docs.urbanairship.com/platform/ios.html

Before the notifications can be retrieved on the mobile device, its important to generate the necessary certificates using the instructions provided at http://docs.urbanairship.com/reference/push-providers/apns.html#ios-apns-setup

Once the notifications are correctly setup and the UrbanAirship services are started, we can retrieve the UrbanAirship ChannelID which will be used to target push notifications for the current device:

// swift
let channelID = UAirship.push().channelID
print("My Application Channel ID: \(channelID)")

Alternatively, since the ChannelID may be null after the first UrbanAirship access, the app can wait and receive the ChannelID in a UARegistrationDelegate implementation, as shown below (and in the UrbanAirship documentation linked above) with the registrationSucceeded function.

A sample AppDelegate file is as follows.

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate, UARegistrationDelegate, UAPushNotificationDelegate {

    var window: UIWindow?
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {       
        let config = UAConfig.default()
        UAirship.takeOff(config)
        
        UAirship.push().notificationOptions = [.alert, .badge, .sound]
        UAirship.push().userPushNotificationsEnabled = true
        
        UAirship.push().registrationDelegate = self
        UAirship.push().pushNotificationDelegate = self
        
        return true
    }
    
    func registrationSucceeded(forChannelID channelID: String, deviceToken: String) {
        print("Registration succeeded. ChannelID: \(channelID)")
    }

    func receivedForegroundNotification(_ notificationContent: UANotificationContent, completionHandler: @escaping () -> Void) {
        print("Received foreground notification. ChannelID: \(UAirship.push().channelID)")        
    }
    
    @available(iOS 10.0, *)
    func presentationOptions(for notification: UNNotification) -> UNNotificationPresentationOptions {
        print("Presentation options")
        return [.alert, .sound]
    }
    
    func receivedBackgroundNotification(_ notificationContent: UANotificationContent, completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        print("Received background notification. ChannelID: \(UAirship.push().channelID)")
    }
}

Rubiq API mobile app registration

The app must be authenticated with the Rubiq API. Use endpoint 2001: Authenticate to authenticate the user, and receive the Rubiq master key for the user, dpKey (See Authenticating requests for more details of how to create requests to the Rubiq API).

Now that the UrbanAirship ChannelID has been successfully retrieved, it needs to be registered with the Rubiq API so push notifications can be sent to the device from the Rubiq Platform. Register the ChannelID against the authenticated Rubiq user's dpKey using Rubiq API endpoint 4001: Register mobile device. For a user with dpKey "12345" and ChannelID "c76ff18e-9cb9-4c19-b9af-a39cae684810", the request URL and body will look like this:

{
    "deviceType": "iOS",
    "deviceID": "c76ff18e-9cb9-4c19-b9af-a39cae684810"
}

Rubiq Platform and UrbanAirship

When a dialogportal Push Activity is produced, the Rubiq Platform builds a push notification payload to send to UrbanAirship. The payload contains the ChannelID, the personalized alert message to be displayed as a notification text, and a messageID. An example with messageID 987654 looks like this:

{
    "audience": {
        "ios_channel": "c76ff18e-9cb9-4c19-b9af-a39cae684810"
    }.
    "notification": {
        "alert": "[Personalized alert message from Push Activity]",
        "ios": {
            "extra": {
                "messageid": "987654",
                "messagetype": "Broadcast"
            },
            "badge": "auto"
        }
    },
    "device_types": [ "ios" ]
}

The messageID is included in the extra section, and is included in the notification payload delivered by UrbanAirship to the device.

Retrieving Push Activity content

The Push Activity that has been generated and now pushed to the recipient devices contains a personalized rich text or HTML body, as well as the alert. The messageID sent with the push notification is the ID to that content, and the app can fetch it by sending the messageID in a request to endpoint 7002: Get message. Alternatively, all available messages can be fetched for the authenticated user by requesting endpoint 7001: Get messages, which includes all previously produced Push Activities which have not expired.