Last fall with the release of Xojo 2020r2, we added the MobileNotifications framework for sending and handling local user notifications to your iOS apps based on time and/or location. This release also included the ability to receive and process remote notifications sent through the Apple Push Notification service (APNs), but as many as you have found, setting up and implementing the infrastructure to send remote notifications is often not a simple thing to do … until now.
Starting in Xojo 2021r2, users with a Xojo Cloud server can deploy web apps which can hook into the Apple Push Notification service directly with a user friendly Xojo API.
Things You Will Need
- An iOS App that is set up to accept remote notifications.
- An Apple Push Notification Certificate. You can get this from your Apple Developer control panel at https://developer.apple.com/account, under Certificates, Identifiers & Profiles. When doing so, you’ll want to make note of your Apple account identifier (in the upper right corner of the window) and the certificate Key ID located in the Key details. Both of these are 10 character alphanumeric codes at this time.
- A Xojo Cloud server. Depending on your needs, even a small server will likely do.
Sending a Basic Remote Notification
The first thing you’ll need to do is to add your APNs certificate to your Xojo Cloud server. This can be done by logging into the Xojo Cloud Control Panel and clicking the Options Tab. There you will find a link that says Manage APNs Certificates. Clicking that will take you to a dialog which allows you to add and remove APNs certificates for a machine.
Sending remote notifications is a relatively simple process, but there’s a little infrastructure you’ll need. Typically the process goes something like this:
In your iOS application which will be receiving the remote notifications, you’ll need to request permission to show notifications (if the notifications will be visible to the user) and then register for remote notifications. When you do this, you’ll be provided with a hex-encoded globally unique token that identifies this device for your app. This identifier should be sent to your notification server along with any information that you may need to determine what type of user this is. This identifier may change from time to time so you should request it whenever your app is launched and send the new one to your server whenever it changes.
In your Xojo Cloud app, sending one or more notifications is relatively easy. You’ll need to create two objects:
- An instance of XojoCloud.RemoteNotifications.DeliveryOptions which is where you’ll put the Application Identifier of the iOS application to which you are sending, the Apple account identifier and the certificate Key ID. This class also defines when the messages you are sending will expire, their priority and their type.
- For each message being sent, you’ll need an instance of XojoCloud.RemoteNotifications.Message which defines the content of the message.
Your code might look something like this:
// Set up Delivery Options
Var deliveryOpts As New XojoCloud.RemoteNotifications.DeliveryOptions(kAppID, kAPNSKeyID, kAppleTeamID)
// Set up a message
Var message As New XojoCloud.RemoteNotifications.Message
message.alertTitle = "Bethany's Bagels – Sale Today!"
message.alertBody = "Today Only – Buy one bagel, get one 50% off!"
message.badge = 1
message.soundName = "default"
// Assuming this RowSet contains all of the device tokens that you are sending to:
Var rs as RowSet = db.SelectSQL(kQueryToGetDeviceTokens)
While Not rs.AfterLastRow
XojoCloud.RemoteNotifications.SendAppleNotification(message, deliveryOpts, rs.Column("token").StringValue)
rs.MoveToNextRow
Wend
rs.close
Sending Notifications With APNs Feedback
The second signature for SendAppleNotification allows you to get feedback from Apple’s Push Notification service, including situations like when a device token is no longer valid which can happen if the user turns off notifications or deletes your app from their device. Because sending messages is asynchronous, you will need to define a callback method and include a pointer to that method when calling SendAppleNotification, like this:
// Signature for the callback method Sub CallbackMethod(MessageID as String, error as RuntimeException)
When you pass the address of the callback method, SendAppleNotification will return a unique message identifier so that if the callback is called, you can identify which notification failed.
Var messageID as String
messageID = XojoCloud.RemoteNotifications.SendAppleNotification(message, deliveryOpts, rs.Column("token").StringValue, AddressOf CallbackMethod)
The possible response codes are defined here.
Advanced Usage
The Xojo Framework covers a large portion of the capabilities of the Apple Push Notification service, but Apple is adding new features all the time. In addition to the two methods described above, there are two methods which take a JSONItem instead of a XojoCloud.RemoteNotifications.Message object. Using this method you can define the message payload which uses features which have not yet been added to the Xojo framework.
Documentation of the JSON payload can be found in the Apple Developer documentation here.
Demo
Here’s a short video showing a remote notification being sent from a Xojo Cloud server in the datacenter in New York City to an iPhone at my house in North Carolina.