5. Sending Your First Push Notification

Written by Scott Grosch

In the last chapter, you set up your app to be able to receive push notifications. The last piece that you’ll need in order to have your app receive a push notification is an Authentication Token used by Apple’s servers to trust your app. This token validates your server and makes sure that there’s always a secure connection between your backend and APNs.

Authentication Token Types

When Apple first started allowing sending push notifications, it used the PKCS #12 archive file format, also commonly known as the PFX format.

If you’ve ever worked with push notifications in the past, this file ends with the .p12 file extension.

This type of format was quite cumbersome to work with for multiple reasons:

• They are only valid for a single year, requiring yearly “maintenance” of your certificates.
• You need separate certificates for both production and development distributions.
• You need separate certificates for every app you publish.
• Apple does not provide the certificate in the “final” format you’ll actually need to send notifications, requiring you to run multiple openssl commands from Terminal for the multiple conversions; usually requiring a bit of research to remember how.

Around 2016, in order to work around the above problems, Apple started supporting the industry standard RFC 7519, better known as JSON Web Tokens, or JWT. These tokens use the newer .p8 file extension.

Apple, of course, likes its own names and so all of its documentation on push notifications refers to these as Authentication Tokens. Changing to the newer format alleviated all the issues of the PFX file format as they do not need to be renewed, don’t differentiate between production and development, and can be used by all of your apps.

Unfortunately, Apple did very little other than say, “There it is!”, when it released it. Unless you already had experience with HTTP/2 and JWT, you were stuck. We’ll remedy that now!

Getting Your Authentication Token

Creating the Authentication Token is a simple process that you only have to do once. In a browser of your choice, go to the Member Center, and sign in with your Apple ID.

1. In the side-bar, click on Keys.
2. Click on the blue “plus” button.

Once you click the plus button, the screen will change where you can enter your key’s details.

1. Name the key Push Notification Key.
2. Enable the Apple Push Notifications service (APNs) checkbox.
3. Press Continue.

Now click Register on the screen that appears, then click Download and, finally, Done.

By default, the key will download to your Downloads directory and will be named something like AuthKey_689R3WVN5F.p8. The 689R3WVN5F part is your Key ID, which you’ll need when you’re ready to send a push.

You’ll also need to know your Team ID, so grab that now. At the very top-right of your browser window you’ll see your Team ID listed right after your account name. It’s a 10 character long string of letters and numbers.

Sending Push Notifications

At this point, you have everything you need to send a push notification to your app. You’ll need some way to actually configure the push and send it manually.

Sending Push Notifications to the Simulator

While you should always test your push notifications against a physical device, during day-to-day development it’ll be easier to test on the simulator so you don’t have to continuously unlock your device.

Create a text file somewhere on your Mac named payload.apns which contains the notification you wish to send, such as the following:

{
  "aps": {
    "alert": "Hello"
  },
  "Simulator Target Bundle": "com.yourcompany.PushNotifications"
}

As you can see, the file is a standard JSON representation of a push notification with two differences. First, you’ve added the Simulator Target Bundle key, which should specify the name of your project’s bundle identifier. Make sure to change that to match your project.

Second, you’ve used an apns extension on the filename. When you drag a file to the simulator with the apns extension, it knows that the file is a push notification payload, as opposed to a file to save.

Build and run the app from Chapter 4, “Xcode Project Setup,” to a simulator. If you skipped Chapter 4 you can find the same project in this chapter’s starter materials.

Once your app is running in the simulator, send it back to the home screen by selecting Devices ▸ Home (⇧ + ⌘ + H). Currently your app will not accept push notifications while running in the foreground. You’ll fix that in Chapter 8, “Handling Common Scenarios”.

Finally, open Finder on your Mac and drag the payload.apns file onto the simulator window. You should see your push notification.

Sending Push Notifications to a Device

There are many free and open-source projects on GitHub which will allow you to send a push notification to your device; consider using PushNotifications as it supports the newer Authentication Keys, which some of the other apps don’t. You can use any of the apps out there as long as they support Authentication Keys.

Build and run the app from Chapter 4, “Xcode Project Setup,” to a physical device. If you skipped chapter 4 you can find the same project in this chapter’s starter materials.

Once the app has successfully launched, move the app to background, by either switching to your home screen or locking the device. With the way your notifications are configured right now, you’ll only see them if you are not currently running the app in the foreground. You’ll fix that later on in the book, in Chapter 8, “Handling Common Scenarios”.

In your Xcode console window (⇧ + ⌘ + C), you’ll see a long hex string printed out, which is the token from your print call during registration. Copy that string into your clipboard.

Now, launch the PushNotifications app you downloaded from GitHub (or any other similar tool). If using PushNotifications, you may need to right-click the app and then select Open to open in, to get around signing restrictions. You’ll need to be sure to select the TOKEN authentication option and then select the p8 file you downloaded from the Developer Portal, and fill in your Key ID, Team ID, Bundle ID and Device Token.

You don’t need to change the payload at all. Once you press Send, you should see a notification appear on your device shortly thereafter!

Key Points

• For your app to receive push notifications, you must have an Authentication Token used by Apple’s servers to trust your app.
• The authentication token validates your server and makes sure that there’s always a secure connection between your backend and APNs.
• Creating the Authentication Token is a simple process that you’re only required to do once; follow the steps in the chapter to create yours.
• To configure the push and send it manually, there are many free and open-source projects on GitHub to provide this functionality — just make sure whatever you use supports Authentication Keys.
• If you’re sending a push notification to the simulator, ensure the file has the apns extension and includes your bundle ID.