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:
- Rubiq needs to know the UrbanAirship
MasterKey
andAppKey
, which can be accessed from the
...
- UrbanAirship App dashboard.
- The UrbanAirship SDK must be integrated into the mobile app
- 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 ChannelID
s, 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 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 the previous versions as well. Depending on the target framework, the relevant instructions can be followed on the link provided previously.
Before the notifications can be retrieved on the mobile device, its important to generate the necessary certificates using the instructions provided at 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 and the ChannelID which would eventually the UrbanAirship ChannelID
which will be used to target push notifications for individual devices. Once this DeviceToken is retrieved successfully, it needs to be registered with Rubiq API so push notifications can be sent out using Rubiq Platform using UrbanAirship SDK. Please note that that in order to push notifications using API, the MasterKey and AppKey are required, which can be accessed from the UrbanAirship App dashboardthe current device:
Code Block | ||||
---|---|---|---|---|
| ||||
// 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.
Code Block | ||||
---|---|---|---|---|
| ||||
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)") // TODO: Register DeviceID with RubiqAPI } 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().deviceToken)") } } 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:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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.