Push notifications have become more and more powerful since they were first introduced. In iOS 10, push notifications can:<\/p>\n
- \n
- Display a short text message<\/li>\n
- Play a notification sound<\/li>\n
- Set a badge number on the app\u2019s icon<\/li>\n
- Provide actions the user can take without opening the app<\/li>\n
- Show a media attachment<\/li>\n
- Be silent, allowing the app to wake up in the background and perform a task<\/li>\n<\/ul>\n
This push notifications tutorial will go over how push notifications work, and let you try out their features.<\/p>\n
Before you get started, you will need the following to test push notifications:<\/p>\n
- \n
- An iOS device<\/em>. Push notifications do not work in the simulator, so you\u2019ll need an actual device.<\/li>\n
- An Apple Developer Program Membership<\/em>. Since Xcode 7, you can 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.<\/li>\n
- Pusher<\/em>. you\u2019ll use this utility app to send notifications to the device. To install, follow the instructions\u00a0here<\/a>.<\/li>\n<\/ul>\n
Getting Started<\/h2>\n
There are three main tasks that must be performed in order to send and receive a push notification:<\/p>\n
- \n
- The app must be configured properly and registered with the Apple Push Notification Service (APNS) to receive push notifications upon every start-up.<\/li>\n
- A server must send a push notification to APNS directed to one or more specific devices.<\/li>\n
- The app must receive the push notification; it can then perform tasks or handle user actions using callbacks in the application delegate.<\/li>\n<\/ol>\n
Tasks 1 and 3 will be the main focus of this push notifications tutorial, since they are the responsibility of an iOS developer.<\/p>\n
Task 2 will also be briefly covered, mostly for testing purposes. Sending push notifications is a responsibility of the app\u2019s server-component and is usually implemented differently from one app to the next. Many apps use third-parties (you can find some good examples\u00a0here<\/a>) to send push notifications, while others use custom solutions and\/or popular libraries (ex.\u00a0Houston<\/a>).<\/p>\n
To get started, download the\u00a0starter project<\/a>\u00a0of\u00a0WenderCast<\/em>. WenderCast is everyone\u2019s go-to source for raywenderlich.com podcasts and breaking news.<\/p>\n
Open\u00a0WenderCast.xcodeproj<\/em>\u00a0in Xcode and take a peek around. Build and run within the iPhone simulator to see the latest podcasts (you\u2019ll use a real device soon!):<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/initial_list-281x500.png\")
<\/a><\/p>\nThe problem with the app is that it doesn\u2019t let users know when a new podcast is available. It also doesn\u2019t really have any news to display. You\u2019ll soon fix all that with the power of push notifications!<\/p>\n
Configuring the Push Notifications Tutorial App<\/h2>\n
Push notifications require a\u00a0lot<\/i>\u00a0of security. This is quite important, since you don\u2019t want anyone else to send push notifications to your users. Unfortunately, this means there\u2019s several required tasks to configure apps for push notifications.<\/p>\n
Enabling the Push Notification Service<\/h3>\n
The first step is to change the App ID. Go to\u00a0App Settings -> General<\/em>\u00a0and change\u00a0Bundle Identifier<\/em>\u00a0to something unique:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/05\/Screen-Shot-2017-05-15-at-23.05.39-1-650x163.png\")
<\/p>\nWithin\u00a0Signing<\/em>\u00a0right below this, select your development\u00a0Team<\/em>. Again, this must be a paid developer account. If you don\u2019t see any teams, you\u2019ll first need to add your development team via\u00a0Xcode -> Preferences -> Accounts -> +<\/em>.<\/p>\n
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\u00a0App Settings -> Capabilities<\/em>\u00a0and flip the switch for\u00a0Push Notifications<\/em>\u00a0to\u00a0On<\/em>.<\/p>\n
After some loading, it should look like this:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_capabilities-480x97.png\")
<\/a><\/p>\nIf any issues occur, visit the\u00a0Apple Developer Center<\/a>. You may simply need to agree to a new developer license, which Apple loves to update ;], and try again. Worse case, you may need to manually add the push notifications entitlement by using the\u00a0+<\/em>\u00a0and\u00a0Edit<\/em>\u00a0buttons.<\/p>\n
Behind the scenes, this creates the App ID and then adds the push notifications entitlement to it. You can log into the Apple Developer Center and verify this:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_configurable-454x500.png\")
<\/a><\/p>\nThat\u2019s all you need to configure for now.<\/p>\n
Registering for Push Notifications<\/h3>\n
There are two steps to register for push notifications. First, you must obtain the user\u2019s permission to show\u00a0any<\/i>\u00a0kind of notification, after which you can register for remote notifications. If all goes well, the system will then provide you with a\u00a0device token<\/em>, which you can think of as an \u201caddress\u201d to this device.<\/p>\n
In WenderCast, you will register for push notifications immediately after the app launches.<\/p>\n
Open\u00a0AppDelegate.swift<\/em>\u00a0and add the following import to the top of the file:<\/p>\n
import<\/span> UserNotifications\r\n<\/pre>\nThen add the following method to the end of\u00a0
AppDelegate<\/code>:<\/p>\nfunc<\/span> registerForPushNotifications<\/span>()<\/span><\/span> {\r\n UNUserNotificationCenter<\/span>.current().requestAuthorization(options: [.alert, .sound, .badge]) {\r\n (granted, error) in<\/span>\r\n print<\/span>(\"Permission granted: \\(granted)<\/span>\"<\/span>)\r\n }\r\n}\r\n<\/pre>\nLastly, add a call to\u00a0
registerForPushNotifications()<\/code>\u00a0at the end of\u00a0application(_:didFinishLaunchingWithOptions:)<\/code>:<\/p>\nfunc<\/span> application<\/span>(\r\n _<\/span> application: UIApplication,\r\n didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?)<\/span><\/span> -> Bool<\/span> {\r\n \/\/ ... existing code ...<\/span>\r\n registerForPushNotifications()\r\n return<\/span> true<\/span>\r\n}\r\n<\/pre>\nLet\u2019s go over the above:\u00a0
UNUserNotificationCenter<\/code>\u00a0was introduced in iOS 10 within the UserNotifications framework. It\u2019s responsible for managing all notification-related activities within the app.<\/p>\nYou invoke\u00a0
requestAuthorization(options:completionHandler:)<\/code>\u00a0to (you guessed it) request authorization for push notifications. Here, you must specify the notification types your app will use. These types (represented by\u00a0UNAuthorizationOptions<\/code>) can be any combination of the following:<\/p>\n- \n
.badge<\/code>\u00a0allows the app to display a number on the corner of the app\u2019s icon.<\/li>\n.sound<\/code>\u00a0allows the app to play a sound.<\/li>\n.alert<\/code>\u00a0allows the app to display text.<\/li>\n.carPlay<\/code>\u00a0allows the app to display notifications in a CarPlay environment.<\/li>\n<\/ul>\nYou call\u00a0
registerForPushNotifications<\/code>\u00a0within\u00a0application(_:didFinishLaunchingWithOptions:)<\/code>\u00a0to ensure the demo app will attempt to register for push notifications any time it\u2019s launched.<\/p>\nBuild and run. When the app launches, you should receive a prompt that asks for permission to send you notifications.<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/IMG_7303-281x500.png\")
<\/a><\/p>\nTap\u00a0OK<\/em>\u00a0and poof! The app can now display notifications. Great! But what now? What if the user declines the permissions? Add this method inside\u00a0
AppDelegate<\/code>:<\/p>\nfunc<\/span> getNotificationSettings<\/span>()<\/span><\/span> {\r\n UNUserNotificationCenter<\/span>.current().getNotificationSettings { (settings) in<\/span>\r\n print<\/span>(\"Notification settings: \\(settings)<\/span>\"<\/span>)\r\n }\r\n}\r\n<\/pre>\nThis method is\u00a0very different<\/i>\u00a0from the previous one. In the previous method, you specified the settings you\u00a0want<\/i>, yet this one returns the settings the user has\u00a0granted<\/i>.<\/p>\n
It\u2019s important to call\u00a0
getNotificationSettings(completionHandler:)<\/code>\u00a0within the completion handler on\u00a0requestAuthorization<\/code>, which happens whenever the app finishes launching. This is because the user can, at any time, go into the Settings app and change the notification permissions.<\/p>\nUpdate\u00a0
requestAuthorization<\/code>\u00a0to call\u00a0getNotificationSettings()<\/code>\u00a0within the completion closure like this:<\/p>\nfunc<\/span> registerForPushNotifications<\/span>()<\/span><\/span> {\r\n UNUserNotificationCenter<\/span>.current().requestAuthorization(options: [.alert, .sound, .badge]) {\r\n (granted, error) in<\/span>\r\n print<\/span>(\"Permission granted: \\(granted)<\/span>\"<\/span>)\r\n\r\n guard<\/span> granted else<\/span> { return<\/span> }\r\n self<\/span>.getNotificationSettings()\r\n }\r\n}\r\n<\/pre>\nStep 1 is now complete, and you\u2019re now ready to actually register for remote notifications!<\/p>\n
Update\u00a0
getNotificationSettings()<\/code>\u00a0with the following:<\/p>\nfunc<\/span> getNotificationSettings<\/span>()<\/span><\/span> {\r\n UNUserNotificationCenter<\/span>.current().getNotificationSettings { (settings) in<\/span>\r\n print<\/span>(\"Notification settings: \\(settings)<\/span>\"<\/span>)\r\n guard<\/span> settings.authorizationStatus == .authorized else<\/span> { return<\/span> }\r\n UIApplication<\/span>.shared.registerForRemoteNotifications()\r\n }\r\n}\r\n<\/pre>\nHere you verify the\u00a0
authorizationStatus<\/code>\u00a0is\u00a0.authorized<\/code>, meaning the user has granted notification permissions, and if so, you call\u00a0UIApplication.shared.registerForRemoteNotifications()<\/code>.<\/p>\nAdd the following two methods to then end of\u00a0
AppDelegate<\/code>; these will be called to inform you about the result of\u00a0registerForRemoteNotifications<\/code>:<\/p>\nfunc<\/span> application<\/span>(_<\/span> application: UIApplication,\r\n didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data)<\/span><\/span> {\r\n let<\/span> tokenParts = deviceToken.map<\/span> { data -> String<\/span> in<\/span>\r\n return<\/span> String<\/span>(format: \"%02.2hhx\"<\/span>, data)\r\n }\r\n \r\n let<\/span> token = tokenParts.joined()\r\n print<\/span>(\"Device Token: \\(token)<\/span>\"<\/span>)\r\n}\r\n\r\nfunc<\/span> application<\/span>(_<\/span> application: UIApplication,\r\n didFailToRegisterForRemoteNotificationsWithError error: Error)<\/span><\/span> {\r\n print<\/span>(\"Failed to register: \\(error)<\/span>\"<\/span>)\r\n}\r\n<\/pre>\nAs the names suggest, the system calls\u00a0
application(_:didRegisterForRemoteNotificationsWithDeviceToken:)<\/code>\u00a0if the registration is successful, or else it calls\u00a0application(_:didFailToRegisterForRemoteNotificationsWithError:)<\/code>.<\/p>\nThe current implementation of\u00a0
application(_:didRegisterForRemoteNotificationsWithDeviceToken:)<\/code>looks cryptic, but it is simply taking\u00a0deviceToken<\/code>\u00a0and 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 \u201caddresses\u201d to deliver notifications to the correct devices.<\/p>\n\nNote:<\/em>\u00a0There are several reasons why registration might fail. Most of the time it\u2019s because the app is running on a simulator, or because the App ID configuration was not done properly. The error message generally provides a good hint for what\u2019s wrong.<\/p>\n<\/div>\n
That\u2019s it! Build and run. Make sure you are running on a device, and you should receive a device token in the console output. Here\u2019s what mine looks like:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_device_token-480x20.png\")
<\/a><\/p>\nCopy this token somewhere handy.<\/p>\n
You have a bit more configuration to do before you can send a push notification, so head over to the\u00a0Apple Developer Member Center<\/a>\u00a0and log in.<\/p>\n
Creating an SSL Certificate and PEM file<\/h3>\n
In your member center, go to\u00a0Certificates, IDs & Profiles -> Identifiers -> App IDs<\/em>\u00a0and select the App ID for your app. Under\u00a0Application Services<\/em>, Push Notifications should show as\u00a0Configurable<\/em>:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_configurable_notifications-480x31.png\")
<\/a><\/p>\nClick\u00a0Edit<\/em>\u00a0and scroll down to\u00a0Push Notifications<\/em>:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_create_cert-650x410.png\")
<\/a><\/p>\nIn\u00a0Development SSL Certificate<\/em>, click\u00a0Create Certificate\u2026<\/em>\u00a0and follow the steps to create a\u00a0CSR<\/em>. Once you have your CSR, click\u00a0continue<\/em>\u00a0and follow the steps to\u00a0Generate<\/em>\u00a0your certificate using the CSR. Finally, download the certificate and double-click it, which should add it to your Keychain, paired with a private key:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_keychain-650x51.png\")
<\/a><\/p>\nBack in the member center, your App ID should now have push notifications enabled for development:<\/p>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/screen_enabled-480x30.png\")
<\/a><\/p>\nWhew! That was a lot to get through, but it was all worth it \u2014 with your new certificate file, you are now ready to send your first push notification!<\/p>\n
Sending a Push Notification<\/h2>\n
Sending push notifications requires an SSL connection to APNS, secured by the push certificate you just created. That\u2019s where\u00a0Pusher<\/em>\u00a0comes in.<\/p>\n
Launch\u00a0Pusher<\/em>. The app will automatically check for push certificates in the Keychain, and list them in a dropdown. Complete the following steps:<\/p>\n
- \n
- \n
- \n
- Select your push certificate from the dropdown.<\/li>\n
- Paste your device token into the \u201cDevice push token\u201d field.<\/li>\n
- Modify the request body to look like this:<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
{\r\n \"aps\"<\/span>: {\r\n \"alert\"<\/span>: \"Breaking News!\"<\/span>,\r\n \"sound\"<\/span>: \"default\"<\/span>,\r\n \"link_url\"<\/span>: \"https:\/\/raywenderlich.com\"<\/span>\r\n }\r\n}\r\n<\/pre>\n- \n
- On the device you previously ran WenderCast on, background the app or lock the device, or else it won\u2019t work*<\/em><\/li>\n
- Click the\u00a0Push<\/em>\u00a0button in Pusher.<\/li>\n<\/ul>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/Screen-Shot-2017-04-30-at-13.02.25-650x312.png\")
<\/a><\/p>\nYou should receive your first push notification:<\/p>\n
- Click the\u00a0Push<\/em>\u00a0button in Pusher.<\/li>\n<\/ul>\n
- On the device you previously ran WenderCast on, background the app or lock the device, or else it won\u2019t work*<\/em><\/li>\n
- An Apple Developer Program Membership<\/em>. Since Xcode 7, you can 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.<\/li>\n
- An iOS device<\/em>. Push notifications do not work in the simulator, so you\u2019ll need an actual device.<\/li>\n
![\"push](\"https:\/\/koenig-media.raywenderlich.com\/uploads\/2017\/04\/IMG_7304-281x500.png\")
<\/a><\/p>\n