8. Displaying Notifications
You can’t connect the dots looking forward; you can only connect them looking backwards. So you have to trust that the dots will somehow connect in your future. You have to trust in something—your gut, destiny, life, karma, whatever. This approach has never let me down, and it has made all the difference in my life.
Steve Jobs
By design, the Apple Watch is an extension of your iPhone. Instead of pulling the iPhone out of your pocket, Apple wants you to look at and perform most of the tasks on your Apple Watch. One of the most common ways a user interacts with the iPhone is through notifications, and the Apple Watch supports that right out of the box.
When an iPhone is paired with an Apple Watch, notifications received by the iPhone are sent to the Apple Watch. Your Apple Watch application then has the option to display the notification to the user in more detail, and the user can also accomplish actions associated with the notifications.
What Is a Notification?
A notification in iOS is a message that informs the user of some information that is coming in. For example, the Messages application may display a notification to inform you that you have an incoming message from a friend, or you may receive a notification informing you that you have a new email message on your mail server. Notifications allow applications that are not running in the foreground to notify the user of new data, and they allow app developers to write useful applications that work even if an application is in the background.
On iOS, a user can receive two types of notifications:
Local notifications: Notifications sent by the app itself. For example, an events-management application may schedule local notifications to be fired at different times to remind users of upcoming events.
Remote notifications (also commonly known as push notifications): Notifications sent from outside the device. For example, a chat application sends a notification to a user when someone sends the user a message.
In iOS 8, Apple added interactive notifications so that you can directly act on a notification when you receive it. A good example is Gmail on the iPhone. The left panel of Figure 8.1 shows a notification about a new email message when the device is unlocked; the notification is shown as a banner at the top of the screen. If you touch the notification and drag it downward, you see two action buttons: Reply and Archive (see Figure 8.1, right).
Tapping the Reply button brings the Gmail application to the foreground so that you can reply to that email message. Tapping the Archive button directly archives the message without bringing Gmail to the foreground. An action button that brings the application to the foreground is known as a foreground action button. Likewise, an action button that does not bring the application to the foreground is known as a background action button. For both types of action buttons, you can configure whether the user must unlock the device before performing the action.
Figure 8.2 shows the same notification received when the device is locked. Swiping the notification to the left reveals the two action buttons. The action button that performs destructive operations (such as deletion, archiving, etc.) is displayed in red.
When the notification is displayed as a banner, at most two action buttons are shown.
To display more than two action buttons, the notification must be configured to display as an alert. Figure 8.3 shows the same notification configured to display as an alert. Tapping the Options button (see Figure 8.3, left) displays another alert with the various action buttons (see Figure 8.3, right).
In Figure 8.3, you see the three action buttons (the first two of which you have already seen): Open, Archive, and Reply.
For this chapter, remember the following points about iOS notifications:
Local notifications emanate from the application itself.
Remote notifications come from outside the device.
An action button can be either a foreground or background action button.
An action button can be configured to perform an action only if the device is unlocked.
An action button that performs destructive operations is displayed in red.
Types of Notifications on the Apple Watch
When notifications (local or remote) are received on the iPhone, iOS decides whether to display them on the iPhone or send them to the Apple Watch.
When the Apple Watch receives a notification, it notifies the user as follows:
First, it displays the notification using a minimal interface, known as the short-look interface. The notification disappears when the user lowers his or her wrist.
If the user’s wrist remains raised or if the user taps the short-look interface, the long-look interface appears. The long-look interface displays the notification in more detail.
Note
If the iPhone is unlocked when a notification arrives, iOS assumes that the iPhone is being used and the notification shows on the iPhone. If the device is locked when the notification arrives, the notification goes to the Apple Watch instead.
For the short-look interface, you don’t have to do much, as the interface is pretty restricted—you can just display the contents of the notification. For the long-look interface, you can customize the details of the notification by displaying additional text or images.
Implementing the Short-Look Interface
Let’s look at how to implement the short-look interface for notifications:
1. Using Xcode, create a new iOS App with WatchKit App project and name it Notifications. Be sure to check the Include Notification Scene option (see Figure 8.4).
2. Examine the Interface.storyboard file located in the WatchKit app (see Figure 8.5). Observe that, in addition to the Interface Controller, you now have two more controllers: Static Interface Controller and Dynamic Interface Controller.
The Static Interface Controller is for displaying the short-look interface, whereas the Dynamic Interface Controller is for displaying the long-look interface. Observe that the Static Interface Controller contains a Label control, which is customizable.
3. Examine the PushNotificationPayload.apns file located in the Extension project’s Support Files group (see Figure 8.6). It is used for simulating receiving a remote (push) notification on the Apple Watch Simulator.
Note
For testing on the Apple Watch Simulator, notifications received by the iPhone Simulator are not sent to the Apple Watch Simulator; instead, you have to use the PushNotificationPayload.apns file to simulate receiving a remote notification.
4. To test the application, select the Notification – Notifications WatchKit App scheme (see Figure 8.7) at the top of Xcode and run it on the iPhone Simulator.
You should see the Apple Watch Simulator displaying a screen containing the app icon, notification title, and app name, followed by the actual notification, as shown in Figure 8.8.
Observe that the Label control displays the text “Test Message,” and the button displays the title “First Button”; both texts come from the PushNotificationPayload.apns file. The Dismiss button is always there, and clicking it dismisses the notification. Clicking First Button invokes the default Interface Controller on the WatchKit application.
Customizing the Notification Message
The Label control on the Static Interface Controller supports text containing line break characters (
). You can use this to break a long line into multiple shorter lines:
1. Using the same project created in the previous section, modify the PushNotificationPayload.apns file as follows:
{
"aps": {
"alert": {
"body":
"Boarding Now
Flight 164 to Los Angeles boards at 6:50AM at
Gate 46",
"title": "Boarding"
},
"category": "myCategory"
},
"WatchKit Simulator Actions": [
{
"title": "First Button",
"identifier": "firstButtonAction"
}
],
"customKey": "Use this file to define a testing payload for your notifications. The aps dictionary specifies the category, alert text, and title. The WatchKit Simulator Actions array can provide info for one or
more action buttons in addition to the standard Dismiss button. Any other
top level keys are custom payload. If you have multiple such JSON files
in your project, you'll be able to select them when choosing to debug the
notification interface of your Watch App."
}
The value of the body key in the PushNotificationPayload.apns file has been formatted for readability. When testing on the iPhone Simulator, it should be a continuous line: “Boarding Now
Flight 164 to Los Angeles boards at 6:50AM at Gate 46.”
2. In the Interface.storyboard file, set the Lines attribute of the Label control on the Static Interface Controller to 0 (see Figure 8.9).
3. Run the application on the iPhone Simulator. On the opening screen, you should now see the “Boarding” word (see Figure 8.10, left). You should now also see the text on the Label control displayed in multiple lines (see Figure 8.10, right). To dismiss the notification, you can scroll the page upward and click the Dismiss button.
Note
You need to dismiss the previous notification (see Figure 8.8) before seeing the new notification.
Modifying the WatchKit Application Name
If you observe the right of Figure 8.10 carefully, you will notice that the Static Interface Controller is displaying the project name of “NOTIFICATION...” (part of it is truncated). You can change this to display a different name:
1. Select the Info.plist file located in the WatchKit app’s Supporting Files group, and modify the value of the Bundle display name key to your desired app name, say, Apple Air (see Figure 8.11).
2. Run the application on the iPhone Simulator, and you should now see both the opening screen and the Static Interface Controller with “Apple Air” in all capital letters (see Figure 8.12).
Setting Icons for the Apple Watch App
All Apple Watch apps submitted to the App Store must have icons. To create an icon, you need to prepare an image in various sizes and then copy it into your project. These icons are then used in various places on the watch: Notification Center, Apple Watch Companion Settings, Home screen, short-look interface, and long-look interface.
1. Prepare a set of icons with the following names and dimensions:
icon48×48.png: 48×48 pixels
icon55×55.png: 55×55 pixels
icon58×58.png: 58×58 pixels
icon87×87.png: 87×87 pixels
icon80×80.png: 80×80 pixels
icon88×88.png: 88×88 pixels
icon172×172.png: 172×172 pixels
icon196×196.png: 196×196 pixels
Note
You can find a copy of these images in the source code download for this book.
2. Select the Assets.xcassets item in the WatchKit App and drag and drop the icons prepared in the previous step onto each of the placeholders as shown in Figure 8.13 (follow the order listed in the previous step).
3. In the Interface.storyboard file, observe that the Static Interface Controller and Dynamic Interface Controller now display the icons (see Figure 8.14).
4. Run the application on the iPhone Simulator. You should now see the icon on the Static Interface Controller (see Figure 8.15).
Setting Background Images
You can also display a background image on the Static Interface Controller:
1. Drag and drop an image named background.png onto the Assets.xcassets file (in the WatchKit app; see Figure 8.16). Be sure to move it into the 2× box in the Apple Watch section.
2. Select the Static Interface Controller in the Interface.storyboard file and set its Background attribute to background (see Figure 8.17). Also, set its Mode attribute to Aspect Fit.
3. Run the application on the iPhone Simulator. You should now see the background image on the Static Interface Controller (see Figure 8.18).
Action Buttons
Earlier, you saw that the PushNotificationPayload.apns file contains the payload of a remote notification. In the WatchKit Simulator Actions key, you saw that you have a single item titled First Button with the identifier of firstButtonAction:
"WatchKit Simulator Actions": [
{
"title": "First Button",
"identifier": "firstButtonAction"
}
],
This item simulates that your remote notification contains a single action button. The title key contains the title of the button to display in the short-look interface, and the identifier key contains the ID of the button that you can programmatically reference when the button is tapped.
You can simulate your remote notification containing multiple action buttons:
1. Modify/add the following statements in bold to the PushNotificationPayload.apns file:
{
"aps": {
"alert": {
"body":
"Boarding Now
Flight 164 to Los Angeles boards at 6:50AM at
Gate 46",
"title": "Boarding"
},
"category": "myCategory"
},
"WatchKit Simulator Actions": [
{
"title": "Itinerary",
"identifier": "btnItinerary"
},
{
"title": "Weather",
"identifier": "btnWeather",
},
{
"title": "Cancel Boarding",
"identifier": "btnCancel",
"destructive": 1
},
],
"customKey": "Use this file to define a testing payload for your
notifications. The aps dictionary specifies the category, alert text, and
title. The WatchKit Simulator Actions array can provide info for one or
more action buttons in addition to the standard Dismiss button. Any other
top level keys are custom payload. If you have multiple such JSON files
in your project, you'll be able to select them when choosing to debug the
notification interface of your Watch App."
}
The destructive key with a value of 1 indicates that this action button is a destructive one.
2. Run the application on the iPhone Simulator. Observe that the short-look interface now displays four buttons (including the Dismiss button), with the destructive action button displayed in red (see Figure 8.19).
Note
Realistically, the short-look interface is short-lived—the user does not have much time to look at the screen and tap the buttons before the short-look interface transitions to the long-look interface.
Handling the Action Buttons
As described at the beginning of this chapter, a notification can contain action buttons. There are two types of action buttons: foreground and background. When a notification is received and displayed on the iPhone, a foreground action button launches the iPhone application and brings it to the foreground, whereas a background action button launches the iPhone application and executes in the background.
On the Apple Watch,
A foreground action button fires either the handleActionWithIdentifier:forLocalNotification: (for local notifications) or handleActionWithIdentifier:forRemoteNotification: (for remote notifications) method of the main Interface Controller for your Watch app.
A background action button fires either the application:handleActionWithIdentifier:forLocalNotification: (for local notifications) or the application:handleActionWithIdentifier:forRemoteNotification: (for remote notifications) method in the containing iOS app.
1. In the Interface.storyboard file, add two Label controls onto the Interface Controller (see Figure 8.20). Set the Lines attributes of both Label controls to 0.
2. Create two outlets for the Label controls. This adds the following statements in bold to the InterfaceController.swift file:
import WatchKit
import Foundation
class InterfaceController: WKInterfaceController {
@IBOutlet var label1: WKInterfaceLabel!
@IBOutlet var label2: WKInterfaceLabel!
override func awakeWithContext(context: AnyObject?) {
super.awakeWithContext(context)
// Configure interface objects here.
}
3. In the PushNotificationPayload.apns file, add the following statements in bold:
{
"aps": {
"alert": {
"body":
"Boarding Now
Flight 164 to Los Angeles boards at 6:50AM at
Gate 46",
"title": "Boarding"
},
"category": "myCategory"
},
"WatchKit Simulator Actions": [
{
"title": "Itinerary",
"identifier": "btnItinerary"
},
{
"title": "Weather",
"identifier": "btnWeather",
},
{
"title": "Cancel Boarding",
"identifier": "btnCancel",
"destructive": 1
},
],
"gateclose":"7:30AM",
"customKey": "Use this file to define a testing payload for your
notifications. The aps dictionary specifies the category, alert text, and
title. The WatchKit Simulator Actions array can provide info for one or
more action buttons in addition to the standard Dismiss button. Any other
top level keys are custom payload. If you have multiple such JSON files
in your project, you'll be able to select them when choosing to debug the
notification interface of your Watch App."
}
4. Add the following statements in bold to the InterfaceController.swift file:
import WatchKit
import Foundation
class InterfaceController: WKInterfaceController {
@IBOutlet var label1: WKInterfaceLabel!
@IBOutlet var label2: WKInterfaceLabel!
override func awakeWithContext(context: AnyObject?) {
super.awakeWithContext(context)
// Configure interface objects here.
label1.setText("")
label2.setText("")
}
func handleButtons (btnIdentifier : String) {
switch btnIdentifier {
case "btnItinerary":
label2.setText("Arriving in Los Angeles at 11:50AM")
case "btnWeather":
label2.setText("The weather in Los Angeles is 62 degrees")
case "btnCancel":
label2.setText("Please proceed to the gate immediately.")
default:break
}
}
//---fired when a foreground action button in a local notification
// is tapped---
override func handleActionWithIdentifier(identifier: String?,
forLocalNotification localNotification: UILocalNotification) {
handleButtons(identifier!)
}
//---fired when a foreground action button in a remote notification
// is tapped---
override func handleActionWithIdentifier(identifier: String?,
forRemoteNotification remoteNotification: [NSObject : AnyObject]) {
if let s = remoteNotification["gateclose"] as? String {
label1.setText("Gate Close: (s)")
}
handleButtons(identifier!)
}
The first argument of the handleActionWithIdentifier:forRemoteNotification: method passes in the identifier of the action button. The second argument passes in a copy of the notification received. Here, you can retrieve the content and use it to get the time the gate closes.
The main entry point for your watch application (which is of type WKInterfaceController) handles all foreground actions of the notifications. The handling is not performed at the Notification Controller.
5. Run the application on the iPhone Simulator and click one of the buttons shown on the Apple Watch Simulator (see Figure 8.21). You should see the main Interface Controller launch, showing the details of the notification.
6. For background actions, you need to implement the application:handleActionWithIdentifier:forLocalNotification: and the application:handleActionWithIdentifier:forRemoteNotification: methods in the containing iOS app. Add the following statements in bold to the AppDelegate.swift file:
import UIKit
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func handleButtons (btnIdentifier : String) {
//...
}
//---fired when a background action button in a local notification
// is tapped---
func application(application: UIApplication,
handleActionWithIdentifier identifier: String?,
forLocalNotification notification: UILocalNotification,
completionHandler: () -> Void) {
handleButtons(identifier!)
}
//---fired when a background action button in a remote notification
// is tapped---
func application(application: UIApplication,
handleActionWithIdentifier identifier: String?,
forRemoteNotification userInfo: [NSObject : AnyObject],
completionHandler: () -> Void) {
handleButtons(identifier!)
}
Note
You can test this code only on an actual iOS device and Apple Watch.
Implementing the Long-Look Interface
When the user taps the short-look interface or keeps his or her wrist raised, the long-look interface appears. The long-look interface allows you to display the notification in more detail (such as using additional Label and Image controls). However, interactions with the user are still not allowed, apart from the action buttons and the Dismiss button. This means that you cannot add your own Button control to the long-look interface. The following steps show you how to implement the long-look interface:
1. Add the following statements in bold to the PushNotificationPayload.apns file:
{
"aps": {
"alert": {
"body":
"Boarding Now
Flight 164 to Los Angeles boards at 6:50AM at
Gate 46",
"title": "Boarding"
},
"category": "myCategory"
},
"WatchKit Simulator Actions": [
{
"title": "Itinerary",
"identifier": "btnItinerary"
},
{
"title": "Weather",
"identifier": "btnWeather",
},
{
"title": "Cancel Boarding",
"identifier": "btnCancel",
"destructive": 1
},
],
"gateclose":"7:30AM",
"status":"Boarding",
"flight":"164",
"time":"6:50AM",
"gate":"46",
"customKey": "Use this file to define a testing payload for your
notifications. The aps dictionary specifies the category, alert text, and
title. The WatchKit Simulator Actions array can provide info for one or
more action buttons in addition to the standard Dismiss button. Any other
top level keys are custom payload. If you have multiple such JSON files
in your project, you'll be able to select them when choosing to debug the
notification interface of your Watch App."
}
The previous statements simulate the notification containing the additional information about a particular flight.
2. In the Interface.storyboard file, add an Image control and three Label controls to the Dynamic Interface Controller (see Figure 8.22). For each of the four controls, set the Horizontal attribute to Center. Also, set the Lines attribute for each of the Label controls to 0.
3. Drag and drop two images named boarding.png and info.png into the Assets.xcassets file located in the WatchKit app (see Figure 8.23).
4. Examine the Dynamic Interface Controller and observe from its Identity Inspector window that its Class is set to NotificationController (see Figure 8.24). This class is represented by the NotificationController.swift file located in the Extension project.
5. Create outlets for the Image and Label controls in the NotificationController.swift file:
import WatchKit
import Foundation
class NotificationController: WKUserNotificationInterfaceController {
@IBOutlet var image: WKInterfaceImage!
@IBOutlet var lblBody: WKInterfaceLabel!
@IBOutlet var lblGate: WKInterfaceLabel!
@IBOutlet var lblTime: WKInterfaceLabel!
override init() {
// Initialize variables here.
super.init()
// Configure interface objects here.
}
6. Add the following statements in bold to the NotificationController.swift file:
import WatchKit
import Foundation
class NotificationController: WKUserNotificationInterfaceController {
@IBOutlet var image: WKInterfaceImage!
@IBOutlet var lblBody: WKInterfaceLabel!
@IBOutlet var lblGate: WKInterfaceLabel!
@IBOutlet var lblTime: WKInterfaceLabel!
override init() {
// Initialize variables here.
super.init()
// Configure interface objects here.
}
override func didReceiveLocalNotification(localNotification:
UILocalNotification, withCompletion completionHandler:
((WKUserNotificationInterfaceType) -> Void)) {
// This method is called when a local notification needs to be
// presented.
// Implement it if you use a dynamic notification interface.
// Populate your dynamic notification interface as quickly as
// possible.
//
// After populating your dynamic notification interface call the
// completion block.
completionHandler(.Custom)
}
override func didReceiveRemoteNotification(remoteNotification:
[NSObject : AnyObject], withCompletion completionHandler:
((WKUserNotificationInterfaceType) -> Void)) {
// This method is called when a remote notification needs to be
// presented.
// Implement it if you use a dynamic notification interface.
// Populate your dynamic notification interface as quickly as
// possible.
//
// After populating your dynamic notification interface call the
// completion block.
let alert = remoteNotification["aps"]!["alert"]! as! NSDictionary
self.lblBody.setText(alert["body"]! as? String)
if remoteNotification["status"] as! String == "Boarding" {
self.image.setImageNamed("boarding")
} else if remoteNotification["status"] as! String == "Delayed" {
self.image.setImageNamed("info")
}
self.lblGate.setText("Gate: " +
(remoteNotification["gate"] as! String))
self.lblTime.setText("Boarding: " + (remoteNotification["time"]
as! String))
completionHandler(.Custom)
}
To implement the long-look interface, you need to implement the following two methods in the NotificationController class:
didReceiveLocalNotification:withCompletion: is fired when a local notification is received.
didReceiveRemoteNotification:withCompletion: is fired when a remote notification is received.
In both methods, you should perform your task quickly. If they take a long time to execute, the Apple Watch will default back to the short-look interface. At the end of the method, you have to call the completion handler, completionHandler, by passing it an enumeration of type WKUserNotificationInterfaceType. Typically, you use Custom, but you can also use Default to default back to the short-look interface if the payload does not contain what you expected.
Because the Apple Watch Simulator simulates only remote notification, add the code in the didReceiveRemoteNotification:withCompletion: method to extract the flight details from the notification payload and display the extra details on the Image and Label controls.
Note
For testing on the Apple Simulator, if you implement the didReceiveRemoteNotification:withCompletion: method and return Custom for the completion handler, the Dynamic Interface Controller is displayed when you run the app on the iPhone Simulator. Otherwise, the Static Interface Controller always loads.
7. Run the application on the iPhone Simulator. You should now see the long-look interface showing the icon and the details of the flight (see Figure 8.25).
Simulating Using Different Notification Payloads
Besides the default PushNotificationPayload.apns file included in the Extension project for simulating a remote notification, you can also add files to simulate additional remote notifications:
1. Right-click the Supporting Files group of the Extension and add a new file. Select iOS | Apple Watch | Notification Simulation File (see Figure 8.26) and click Next. Name the file NotificationPayload-delayed. The file should now appear in the Supporting Files group (see Figure 8.27).
2. Populate the NotificationPayload-delayed.apns file as follows:
Note
The value of the body key in the NotificationPayload-delayed.apns file has been formatted for readability. When testing on the iPhone Simulator, it should be a continuous line: “Flight Delayed
Flight 164 to Los Angeles now boards at 7:50AM at Gate 56.”
{
"aps": {
"alert": {
"body": "Flight Delayed
Flight 164 to Los Angeles now
boards at 7:50AM at Gate 56",
"title": "Apple Air"
},
"category": "myCategory"
},
"status": "Delayed",
"flight" :"164",
"time": "7:50AM",
"gate": "56",
"gateclose":"8:30AM",
"WatchKit Simulator Actions": [
{
"title": "Itinerary",
"identifier": "btnItinerary"
},
{
"title": "Weather",
"identifier": "btnWeather",
},
{
"title": "Cancel Boarding",
"identifier": "btnCancel",
"destructive": 1
},
]
}
3. To select the newly added payload file for testing, select the Edit Scheme... item located at the top of Xcode (see Figure 8.28).
4. In the Run configuration, select NotificationPayload-delayed.apns as the Notification Payload (see Figure 8.29).
5. Run the application on the iPhone Simulator. You should now see the long-look interface showing a different set of icons and details of the flight (see Figure 8.30).
Changing Sash Color
Both the Static Interface Controller and the Dynamic Interface Controller allow you to change their sash colors and title colors:
1. Select the myCategory arrow in the Interface.storyboard file and, in the Attributes Inspector window, change its Sash Color to Yellow and Title Color to Blue (see Figure 8.31). You should immediately see the changes in color.
2. Run the application on the iPhone Simulator, and observe the sash and title colors in the Dynamic Interface Controller (see Figure 8.32).
Summary
In this chapter, you learned how to implement notifications in your Apple Watch apps. You learned about the different types of notifications and how they are handled in the Apple Watch. You also saw how to simulate notifications with different payloads. In the next chapter, you learn how to implement glances in your Apple Watch apps.