Push Notifications Tutorial: Getting Started

Learn how to get started with push notifications!

iOS developers love to imagine users of their awesome app using the app all day, every day. Unfortunately, the cold hard truth is that users will sometimes have to close the app and perform other activities. Laundry doesn’t fold itself, you know :]

Happily, push notifications allow developers to reach users and perform small tasks even when users aren’t actively using an app!

Push notifications have become more and more powerful since they were first introduced. In iOS 9, push notifications can:

• Display a short text message
• Play a notification sound
• Set a badge number on the app’s icon
• Provide actions the user can take without opening the app
• Be silent, allowing the app to wake up in the background and perform a task

This push notifications tutorial will go over how push notifications work, and let you try out their features.

Before you get started, you will need the following to test push notifications:

• An iOS device. Push notifications do not work in the simulator, so you’ll need an actual device.
• An Apple Developer Program Membership. Since Xcode 7, you can now test apps on your device without a program membership. However, to configure push notifications you need a push notification certificate for your App ID, which requires the program membership.

Getting Started

There are three main tasks that must be performed in order to send and receive a push notification:

1. The app must be configured properly and registered with the Apple Push Notification Service (APNS) to receive push notifications upon every start-up.
2. A server must send a push notification to APNS directed to one or more specific devices.
3. The app must receive the push notification; it can then perform tasks or handle user actions using callbacks in the application delegate.

Tasks 1 and 3 will be the main focus of this push notifications tutorial, since they are the responsibility of an iOS developer.

Task 2 will also be briefly covered, mostly for testing purposes. Sending push notifications is a responsibility of the app’s server-component and is usually implemented differently from one app to the next. Many apps use third-parties (ex. Parse.com or Google Cloud Messaging) to send push notifications, while others use custom solutions and/or popular libraries (ex. Houston).

To get started, download the starter project of WenderCast. WenderCast is everyone’s go-to source for raywenderlich.com podcasts and breaking news.

Open WenderCast.xcodeproj in Xcode and take a peek around. Build and run to see the latest podcasts:

The problem with the app is that it doesn’t let users know when a new podcast is available. It also doesn’t really have any news to display. You’ll soon fix all that with the power of push notifications!

Configuring an App for Push Notifications

Push notifications require a lot of security. This is quite important, since you don’t want anyone else to send push notifications to your users. What this means is that there are quite a few hoops to jump through to configure apps for push notifications.

Enabling the Push Notification Service

The first step is to change the App ID. Go to App Settings -> General and change Bundle Identifier to something unique:

Next, you need to create an App ID in your developer account that has the push notification entitlement enabled. Luckily, Xcode has a simple way to do this. Go to App Settings -> Capabilities and flip the switch for Push Notifications to On.

After some loading, it should look like this:

Behind the scenes, this creates the App ID in your member center if it doesn’t exist already, then adds the push notifications entitlement to it. You can log in and verify this:

If any issues occur, manually create the App ID or add the push notifications entitlement in the member center by using the + or Edit buttons.

That’s all you need to configure for now.

Registering for Push Notifications

There are two steps to register for push notifications. First, you must obtain the user’s permission to show any kind of notification, after which you can register for remote notifications. If all goes well, the system will then provide you with a device token, which you can think of as an “address” to this device.

In WenderCast, you will register for push notifications immediately after the app launches.

Open AppDelegate.swift and add the following method to the end of AppDelegate:

func registerForPushNotifications(application: UIApplication) {
  let notificationSettings = UIUserNotificationSettings(
    forTypes: [.Badge, .Sound, .Alert], categories: nil)
  application.registerUserNotificationSettings(notificationSettings)
}

This method creates an instance of UIUserNotificationSettings and passes it to registerUserNotificationSettings(_:).

UIUserNotificationSettings stores settings for the type of notification your app will use. For the UIUserNotificationTypes, you can use any combination of the following:

• .Badge allows the app to display a number on the corner of the app’s icon.
• .Sound allows the app to play a sound.
• .Alert allows the app to display text.

The set of UIUserNotificationCategorys that you currently pass nil to allows you to specify different categories of notifications your app can handle. This becomes necessary when you want to implement actionable notifications, which you will use later.

Add a call to registerForPushNotifications(_:) as the first line in application(_:didFinishLaunchingWithOptions:launchOptions:):

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  registerForPushNotifications(application)
  //...
}

Build and run. When the app launches, you should receive a prompt that asks for permission to send you notifications:

Tap OK and poof! The app can now display notifications. Great! But what now? What if the user declines the permissions?

When the user accepts or declines your permissions or has already made that selection in the past, a delegate method of UIApplicationDelegate gets called. Add this method inside AppDelegate:

func application(application: UIApplication, didRegisterUserNotificationSettings notificationSettings: UIUserNotificationSettings) {
 
}

In this method, you get passed another UIUserNotificationSettings. This one is very different from the previous one you passed in. That one specified the settings you want, while this one specifies the settings the user has granted.

It’s extremely important to call registerUserNotificationSettings(_:) every time the app launches. This is because the user can, at any time, go into the Settings app and change the notification permissions. application(_:didRegisterUserNotificationSettings:) will always provide you with what permissions the user currently has allowed for your app.

Step 1 is now complete, and you can now register for remote notifications. This is slightly easier, since you don’t need more permissions from the user. Update application(_:didRegisterUserNotificationSettings:) with the following:

func application(application: UIApplication, didRegisterUserNotificationSettings notificationSettings: UIUserNotificationSettings) {
  if notificationSettings.types != .None {
    application.registerForRemoteNotifications()
  }
}

Here, you first check whether the user has granted you any notification permissions; if they have, you directly call registerForRemoteNotifications().

Again, methods in UIApplicationDelegate are called to inform you about the status of registerForRemoteNotifications().

Add the following two methods to AppDelegate:

func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
  let tokenChars = UnsafePointer<CChar>(deviceToken.bytes)
  var tokenString = ""
 
  for i in 0..<deviceToken.length {
    tokenString += String(format: "%02.2hhx", arguments: [tokenChars[i]])
  }
 
  print("Device Token:", tokenString)
}
 
func application(application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: NSError) {
  print("Failed to register:", error)
}

As the names suggest, the system calls application(_:didRegisterForRemoteNotificationsWithDeviceToken:) when the registration is successful, and otherwise calls application(_:didFailToRegisterForRemoteNotificationsWithError:).

The current implementation of application(_:didRegisterForRemoteNotificationsWithDeviceToken:) looks cryptic, but it is simply taking deviceToken and converting it to a string. The device token is the fruit of this process. It is a token provided by APNS that uniquely identifies this app on this particular device. When sending a push notification, the app uses device tokens as “addresses” to direct notifications to the correct devices.

That’s it! Build and run. Make sure you are running on a device, and you should receive a device token in the console output. Here’s what mine looks like:

Copy this token somewhere handy.

You have a bit more configuration to do before you can send a push notification, so return to Apple’s Developer Member Center.

Creating an SSL Certificate and PEM file

In your member center, go to Certificates, Identifiers & Profiles -> Identifiers -> App IDs and find the App ID for your app. Under Application Services, Push Notifications should be Configurable:

Click Edit and scroll down to Push Notifications:

In Development SSL Certificate, click Create Certificate… and follow the steps to create a CSR. Once you have your CSR, click continue and Generate your certificate using the CSR. Finally, download the certificate and run it, which should add it to your Keychain, paired with a private key:

Back in the member center, your App ID should now have push notifications enabled for development:

There is one last thing you need before you close Keychain Access. Right-click on your new push certificate and choose Export:

Save it as WenderCastPush.p12 to Desktop as a .p12 file:

You will be prompted to enter a password for the p12. You can either leave this blank or enter a password of your choosing. I used “WenderCastPush” as the password. You’ll then need to enter your log-in password to permit the export.

Next, open up your terminal and run the following commands to generate a PEM file from the p12 file:

$ cd ~/Desktop
$ openssl pkcs12 -in WenderCastPush.p12 -out WenderCastPush.pem -nodes -clcerts

If you created a password for the p12 file, you will need to enter it here.

Whew! That was a lot to get through, but it was all worth it — with your new WenderCastPush.pem file, you are now ready to send your first push notification!

Sending a Push Notification

The starter kit includes a folder called WenderCastPush; inside are two simple scripts that send push notifications. The one you will be using is newspush.php. As its name suggests, this script sends breaking news to your users.

Sending push notifications requires an SSL connection to APNS, secured by the push certificate you just created. That’s where WenderCastPush.pem comes in. Rename WenderCastPush.pem to ck.pem and replace the existing ck.pem in the WenderCastPush folder.

Open newspush.php and update $deviceToken to the one you received earlier, and $passphrase to the password you gave your push certificate when exporting:

// Put your device token here (without spaces):
$deviceToken = '43e798c31a282d129a34d84472bbdd7632562ff0732b58a85a27c5d9fdf59b69';
 
// Put your private key's passphrase here:
$passphrase = 'WenderCastPush';

Open your terminal, cd to the folder containing newspush.php and type:

$ php newspush.php 'Breaking News' 'https://raywenderlich.com'

If all goes well, your terminal should display:

Connected to APNS
Message successfully delivered

You should receive your first push notification:

Common Issues

There are a couple problems that might arise:

Some notifications received but not all: If you’re sending multiple push notifications simultaneously and only a few are received, fear not! That is intended behaviour. APNS maintains a QoS (Quality of Service) queue for each device with a push app. The size of this queue is 1, so if you send multiple notifications, the last notification is overridden.

Problem connecting to Push Notification Service: One possibility could be that there is a firewall blocking the ports used by APNS. Make sure you unblock these ports. Another possibility might be that the private key and CSR file are wrong. Remember that each App ID has a unique CSR and private key combination.

Anatomy of a Basic Push Notification

Before you move on to Task 3, handling push notifications, take a look at newspush.php to get a basic idea of what a push notification looks like.

Pay attention to lines 32-40. Here the payload body is created and encoded as JSON. This is what actually gets sent to APNS. In this case, the payload looks like this:

{
  "aps":
  {
    "alert": "Breaking News!",
    "sound": "default"
    "link_url" : "https://raywenderlich.com,
  }
}

For the JSON-uninitiated, a block delimited by curly { } brackets contains a dictionary that consists of key/value pairs (just like an NSDictionary).

The payload is a dictionary that contains at least one item, aps, which itself is also a dictionary. In this example, “aps” contains the fields “alert,” “sound,” and “link_url.” When this push notification is received, it shows an alert view with the text “Breaking News!” and plays the standard sound effect.

“link_url” is actually a custom field. You can add custom fields to the payload like this and they will get delivered to your application. Since you aren’t handling it inside the app yet, this key/value pair currently does nothing.

There are five keys you can add to the aps dictionary:

• alert. This can be a string, like in the previous example, or a dictionary itself. As a dictionary, it can localize the text or change other aspects of the notification. See Apple’s documentation for all the keys it can support.
• badge. This is a number that will display in the corner of the app icon. You can remove the badge by setting this to 0.
• sound. By setting this key, you can play custom notification sounds located in the app in place of the default notification sound. Custom notification sounds must be shorter than 30 seconds and have a few restrictions, which you can see in Apple’s documentation.
• content-available. By setting this key to 1, the push notification becomes a silent one. This will be explored later in this push notifications tutorial.
• category. This defines the category of the notification, which is is used to show custom actions on the notification. You will also be exploring this shortly.

Outside of these, you can add as much custom data as you want, as long as the payload does not exceed the maximum size of 4096 bytes.

Once you’ve had enough fun sending push notifications to your device, move on to the next section. :]

Handling Push Notifications

In this section, you’ll learn how to perform actions in your app when push notifications are received and/or when users tap on them.

What Happens When You Receive a Push Notification?

When your app receives a push notification, a method in UIApplicationDelegate is called.

The notification needs to be handled differently depending on what state your app is in when it’s received:

• If your app wasn’t running and the user launches it by tapping the push notification, the push notification is passed to your app in the launchOptions of application(_:didFinishLaunchingWithOptions:).
• If your app was running and in the foreground, the push notification will not be shown, but application(_:didReceiveRemoteNotification:) will be called immediately.
• If your app was running or suspended in the background and the user brings it to the foreground by tapping the push notification, application(_:didReceiveRemoteNotification:) will be called.

In the first case, WenderCast will create the news item and open up directly to the news section. Add the following code to the end of application(_:didFinishLaunchingWithOptions:), before the return statement:

// Check if launched from notification
// 1
if let notification = launchOptions?[UIApplicationLaunchOptionsRemoteNotificationKey] as? [String: AnyObject] {
  // 2
  let aps = notification["aps"] as! [String: AnyObject]
  createNewNewsItem(aps)
  // 3
  (window?.rootViewController as? UITabBarController)?.selectedIndex = 1
}

This code does three things:

1. It checks whether the value for UIApplicationLaunchOptionsRemoteNotificationKey exists in launchOptions. If it does, this will be the push notification payload you sent.
2. If it exists, you grab the aps dictionary from it and pass it to createNewNewsItem(_:), which is a helper method provided to create a NewsItem from the dictionary and refresh the news table.
3. Changes the selected tab of the tab controller to 1, the news section.

To test this, you need to edit the scheme of WenderCast:

Under Run -> Info, select Wait for executable to be launched:

This option will make the debugger wait for the app to be launched for the first time after installing to attach to it.

Build and run. Once it’s done installing, send out some breaking news again. Tap on the notification, and the app should open up to some news:

To handle the other two cases, add the following method to AppDelegate:

func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject]) {
  let aps = userInfo["aps"] as! [String: AnyObject]
  createNewNewsItem(aps)
}

This method directly uses the helper function to create a new NewsItem. You can now change the scheme back to launching the app automatically if you like.

Build and run. Keep the app running in the foreground and on the News section. Send another news push notification and watch as it magically appears in the feed:

That’s it! Your app can now handle breaking news in this basic way.

Something important thing to note: many times, push notifications may be missed. This is ok for WenderCast, since having the full list of news isn’t too important in this app, but in general you should not use push notifications as the only way of delivering content. Instead, push notifications should signal that there is new content available and let the app download the content from the source. WenderCast is a bit limited in this sense, as it doesn’t have a proper server-side component.

Actionable Notifications

Actionable notifications let you add custom buttons to the notification itself. You may have noticed this on email notifications or Tweets that let you “reply” or “favorite” on the spot.

Actionable notifications are defined by your app when you register for notifications by using categories. Each category of notification can have a few preset custom actions.

Once registered, your server can set the category of a push notification; the corresponding actions will be available to the user when received.

For WenderCast, you will define a “News” category with a custom action “View” which allows users to directly view the news article in the app if they choose to.

Add the following code to the beginning of registerForPushNotifications(_:):

let viewAction = UIMutableUserNotificationAction()
viewAction.identifier = "VIEW_IDENTIFIER"
viewAction.title = "View"
viewAction.activationMode = .Foreground

This creates a new notification action with the title View on the button, and opens the app into the foreground when triggered. The action has the identifier VIEW_IDENTIFIER, which is used to differentiate between different actions on the same notification.

Add the following snippet right after the previous one:

let newsCategory = UIMutableUserNotificationCategory()
newsCategory.identifier = "NEWS_CATEGORY"
newsCategory.setActions([viewAction], forContext: .Default)

This defines the news category with the view action for a default context. The identifier NEWS_CATEGORY is what your payload will need to contain to specify that the push notification belongs to this category.

Finally, pass it into the constructor for UIUserNotificationSettings by changing the existing line to:

let notificationSettings = UIUserNotificationSettings(forTypes: [.Badge, .Sound, .Alert], categories: [newsCategory])

That’s it! Build and run the app to register the new notification settings. Press the home button to close the app so the push notification will be visible.

Before you run newspush.php again, first perform a small modification to specify the category. Open newspush.php and modify the payload body to include the category:

$body['aps'] = array(
  'alert' => $message,
  'sound' => 'default',
  'link_url' => $url,
  'category' => 'NEWS_CATEGORY',
  );

Save and close newspush.php, then run it to send another push notification. If all goes well, you should be able to pull down or swipe on the notification to reveal the View action:

Nice! Tapping on it will launch WenderCast but not do anything. To get it to display the news item, you need to do some more event handling in the delegate.

Handling Notification Actions

Back in AppDelegate.swift, add another method:

func application(application: UIApplication, handleActionWithIdentifier identifier: String?, forRemoteNotification userInfo: [NSObject : AnyObject], completionHandler: () -> Void) {
  // 1
  let aps = userInfo["aps"] as! [String: AnyObject]
 
  // 2
  if let newsItem = createNewNewsItem(aps) {
    (window?.rootViewController as? UITabBarController)?.selectedIndex = 1
 
    // 3
    if identifier == "VIEW_IDENTIFIER", let url = NSURL(string: newsItem.link) {
      let safari = SFSafariViewController(URL: url)
      window?.rootViewController?.presentViewController(safari, animated: true, completion: nil)
    }
  }
 
  // 4
  completionHandler()
}

This is the callback you get when the app is opened by a custom action. It might look like there’s a lot going on, but there’s really not much new here. The code:

1. Gets the aps dictionary.
2. Creates the NewsItem from the dictionary and goes to the News section.
3. Checks the action identifier, which is passed in as identifier. If it is the “View” action and the link is a valid URL, it displays the link in a SFSafariViewController.
4. Calls the completion handler that is passed to you by the system after handling the action.

Build and run. Close the app again, then send another news notification. Make sure the URL is valid:

$ php newspush.php 'New Posts!' 'https://raywenderlich.com'

Tap on the action, and you should see WenderCast present a Safari View Controller right after it launches:

Congratulations, you’ve just implemented an actionable notification! Send a few more and try opening the notification in different ways to see how it behaves.

Silent Push Notifications

Silent push notifications can wake your app up silently to perform some tasks in the background. WenderCast can use this feature to quietly refresh the podcast list.

As you can imagine, with a proper server-component this can be very efficient. Your app won’t need to poll for data constantly — you can send it a silent push notification whenever new data is available.

To get started, go to App Settings -> Capabilites and turn on Background Modes for WenderCast. Check the last option, Remote Notifications:

Now your app will wake up in the background when it receives one of these push notifications.

Inside AppDelegate, replace application(_:didReceiveRemoteNotification:) with this more powerful version:

func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
  let aps = userInfo["aps"] as! [String: AnyObject]
 
  // 1
  if (aps["content-available"] as? NSString)?.integerValue == 1 {
    // Refresh Podcast
    // 2
    let podcastStore = PodcastStore.sharedStore
    podcastStore.refreshItems { didLoadNewItems in
      // 3
      completionHandler(didLoadNewItems ? .NewData : .NoData)
    }
  } else  {
    // News
    // 4
    createNewNewsItem(aps)
    completionHandler(.NewData)
  }
}

This code:

1. Checks to see if content-available is set to 1, to see whether or not it is a silent notification.
2. Refreshes the podcast list, which is a network call and therefore asynchronous.
3. When the list is refreshed, calls the completion handler and lets the system know whether any new data was loaded.
4. If it isn’t a silent notification, assumes it is news again and create a news item.

Be sure to call the completion handler and be honest about the result. The system measures the battery consumption and time that your app uses in the background, and may throttle you if needed.

That’s all there is to it; now you can use contentpush.php to send the silent push notification to your app. Make sure to modify the settings of that script as well:

// Put your device token here (without spaces):
$deviceToken = '43e798c31a282d129a34d84472bbdd7632562ff0732b58a85a27c5d9fdf59b69';
 
// Put your private key's passphrase here:
$passphrase = 'WenderCastPush';

Directly run it in the terminal:

$ php contentpush.php

If all goes well, nothing should happen! To see the code being run, change the scheme to “Wait for executable to be launched” again and set a breakpoint within application(_:didReceiveRemoteNotification:fetchCompletionHandler:) to make sure it runs.

Where To Go From Here?

Congrats — you’ve completed this push notifications tutorial and made WenderCast a fully-featured app with push notifications!

You can download the completed project here. Remember that you will still need to change the bundle ID and create certificates to make it work.

Even though push notifications are an important part of apps nowadays, it’s also very common for users to decline permissions to your app if notifications are sent too often. But with thoughtful design, push notifications can keep your users coming back to your app again and again!

This cat received a push notification that his dinner was ready

I hope you’ve enjoyed this push notifications tutorial; if you have any questions feel free to leave them in the discussion below.

The post Push Notifications Tutorial: Getting Started appeared first on Ray Wenderlich.