Page Comparison

iOS

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

...

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

The UrbanAirship SDK supports the new rich notifications provided by iOS 10+, as well as provides support for previous versions. Depending on the target framework, the relevant instructions can be followed on the site linked above.

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 DeviceToken (either DeviceToken or ChannelID) which would eventually the UrbanAirship ChannelID which will be used to target push notifications for individual devices. Once this DeviceIToken is retrieved successfully, it needs to be registered with the RubiqAPI so push notifications can be sent out from the Rubiq Platform via the UrbanAirship SDK.

The exact location for registering the DeviceToken depends on the flow of the app. This could for instance be soon after a user has successfully logged in to the app using Rubiq API endpoint 2001: Authenticate. On successful authentication, dialogportal's master key would be returned as a part of the response. This Master key along with the DeviceID could then be used to register the device using Rubiq API endpoint 4001: Register mobile device.

...

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), DeviceToken: \(deviceToken)")
    }

    func receivedForegroundNotification(_ notificationContent: UANotificationContent, completionHandler: @escaping () -> Void) {
        print("Received foreground notification. DeviceTokenChannelID: \(UAirship.push().deviceTokenchannelID)")        
     }
    
    @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. DeviceTokenChannelID: \(UAirship.push().deviceTokenchannelID)")
    }
}

A sample code for generating the encrypted token using Swift is provided below. The prerequisite is that the raw token has already been generated as defined in Authenticating requests. The library used for generating the encrypted token is CryptoSwift https://github.com/krzyzanowskim/CryptoSwift.

func createEncryptedToken(_ rawToken: String, _ apiSecret: String) -> String {
	let appSecretBytes = apiSecret.utf8.map({$0})
    let tokenBytes = rawToken.utf8.map({$0})
    let encryptedBytes = try! HMAC(key: appSecretBytes, variant: .sha256).authenticate(tokenBytes)
    return encryptedBytes.toBase64()!
}

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.