Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Notification Essentials

Local and remote notifications are a way to communicate information to the user even when your app is not running. Apps schedule local notifications directly, specifying a time or location value to use to trigger the notification’s delivery. Your server sends remote notifications to the user’s iPhone via the Apple Push Notification service (APNs) and those notifications are communicated to the user’s Apple Watch as appropriate.

Apps that do nothing to support notifications still get some notification behavior for free, but customizing your app’s notification support is a great way to improve the watchOS experience. You can customize your Watch app’s notification support in the following ways:

  • Respond to the delivery of local and remote notifications.

  • Provide custom interfaces for delivered notifications.

  • Schedule local notifications directly from your Watch app.

  • Add support for actionable notifications so that users can respond directly from the notification interface.

In watchOS 3 and later, you use the User Notifications framework to schedule and handle local notifications. You also use that framework to handle remote notifications forwarded to your Watch app by the user’s iPhone. For information about how to schedule and handle local and remote notifications, see Local and Remote Notification Programming Guide. For additional information about the classes of the User Notifications framework, see User Notifications Framework Reference.

The Short-Look Interface

When a notification first arrives on Apple Watch, the system displays the short-look interface, an example of which is shown in Figure 19-1. The short-look interface is a nonscrolling screen that cannot be customized. The system uses a template to display the app name and icon along with the title string stored in the local notification or remote notification payload. If the user continues to look at the notification, the system transitions quickly from the short-look interface to the long-look interface.

Figure 19-1A short-look interface image: ../Art/shortlook_calendar_2x.png

The title string used in the short look provides a brief indication of the intent of the notification. For local notifications, you specify this string using the title property of the UNMutableNotificationContent object you create for the notification. For remote notifications, you specify this string using the title key of the alert dictionary inside the payload. For more information about configuring the content of your notifications, see Local and Remote Notification Programming Guide.

The Long-Look Interface

The long-look interface is a scrollable screen that displays the notification’s content and any associated action buttons. If you do not provide a custom notification interface, Apple Watch displays a default interface that includes your app icon, the title string of the notification, and the alert message. If you provide a custom notification interface, Apple Watch displays your custom interface instead.

The long-look notification interface is divided into three areas:

  • The sash is an overlay that contains the app icon and app name. The sash color is configurable.

  • The content area contains the detailed information about the incoming notification. For information on how to customize the content in this area, see Managing a Custom Long Look Interface.

  • The bottom area contains a Dismiss button and any action buttons registered by the containing iOS app.

Figure 19-2 shows an example of a long-look notification containing several action buttons.

Figure 19-2A long-look notification interface image: ../Art/longlook_calendar_2x.png

Tapping the app icon launches your Watch app. Tapping one of the app-defined action buttons delivers the selected action to either your iOS app or your Watch app. (Foreground actions are always delivered to your Watch app. Background actions for local notifications are delivered to your Watch app, but background actions for remote notifications are delivered to your iOS app.) Tapping the Dismiss button closes the notification interface and notifies your app if you asked to be notified. Tapping anywhere else does nothing.

For information about how to provide a custom long-look interface for your app, see Managing a Custom Long Look Interface.

Where Are Notifications Delivered?

Apple Watch and iPhone work together to deliver notifications to the user. Instead of notifications appearing on both devices, notifications appear on the single device that is most likely to have the user’s current focus. The system decides which device receives the notification based on the type of the notification, on which process created the notification, and on which device is active. Table 19-1 lists the rules that iOS and watchOS use for determining where to deliver notifications.

Table 19-1Notification delivery matrix

Notification Type

Source

Destination

Local

iOS app

Either Apple Watch or iPhone, depending on the locked/unlocked state of both devices.

Local

WatchKit extension

Apple Watch only

Remote

Your server

Either Apple Watch or iPhone, depending on the locked/unlocked state of both devices.

Silent

Your server

iPhone only

For notifications that can be delivered to either device, the system uses the locked state of the Apple Watch and iPhone to determine the destination. When Apple Watch is on the user’s wrist and unlocked, notifications are delivered to Apple Watch. One exception occurs when the user’s iPhone is also unlocked and the screen is on, in which case notifications are delivered to iPhone. When Apple Watch is not on the user’s wrist or is not unlocked, notifications are delivered to iPhone. If the user has more than one Apple Watch, local notifications scheduled by your Watch app on one device are delivered to that device only.

Remote notifications are always received by the user’s iPhone before being routed to the appropriate device. Because silent notifications do not result in any user interactions, they are always handled by your iOS app and are never forwarded to Apple Watch.

If your Watch app is in the foreground when a local or remote notification is delivered, the system calls the userNotificationCenter:willPresentNotification:withCompletionHandler: method of your user notification center delegate so that you can decide what to do. You have the option of handling the notification silently or asking the system to alert the user. If you do not implement that method, the system silences the notification and does not deliver it to your Watch app.

For additional information about handling notifications, see Local and Remote Notification Programming Guide.

Requesting Authorization for User Interactions

Before the system can post alerts or play sounds for your app’s notifications, your Watch app or iOS app must request authorization to interact with the user. You do this by calling the requestAuthorizationWithOptions:completionHandler: method of the shared UNUserNotificationCenter object. You must call this method before performing operations involving local or remote notifications. For example, you might call this method during your app’s launch cycle. When either your Watch app or iOS app is launched for the first time, this method prompts the user to grant the requested authorization. Subsequent launches of either app do not prompt the user again.

For information about how to request authorization to interact with the user, see Local and Remote Notification Programming Guide.

Configuring Actionable Notifications

A long look containing app-defined action buttons is known as an actionable notification, because it lets the user perform explicit actions in response to the notification. The process for configuring the actions for your notifications is separate from the process of scheduling and handling the notifications themselves. Early in your app’s launch cycle, register one or more notification categories and specify the custom actions you want associated with each one. During the registration process, you specify the title to use for each action button and the behavior of that action when pressed.

To display a group of actions for a notification, include the name of the relevant category in the notification content. For local notifications, specify the category name using the categoryIdentifier property of your UNMutableNotificationContent object. For remote notifications, your server specifies this name as the value of the category key in the remote notification’s payload. At delivery time, the system uses the category name to look up the associated actions. It then creates buttons for each action and attaches those buttons to the notification interface.

For information about how to configure the categories and actions for your Watch app, see Local and Remote Notification Programming Guide.

Responding to Selected Actions

When the user taps an action button for a notification, the user’s response is delivered to your iOS app or Watch for handling. Which app receives the response depends on whether the action was configured as a foreground or background action.

  • Foreground actions are always handled by the app that was launched in response to the action. For example, if the user selects a foreground action on Apple Watch, the system launches your Watch app and delivers the user’s response to it.

  • For background actions, the handling of actions depends on where the notification was scheduled:

    • For local notifications scheduled on Apple Watch, background actions are handled by your Watch app.

    • For local notifications scheduled on iPhone, background actions are handled by your iOS app regardless of which device displayed the notification.

    • For remote notifications, background actions are always handled by your iOS app, regardless of which device displayed the notification.

You specify whether an action is a foreground or background action when registering your app’s categories and actions. Actions are configured as background actions by default. If you want to handle the action in the foreground, you must specify the UNNotificationActionOptionForeground option when creating the UNNotificationAction object.

Offering Text Input Suggestions to the User

To provide suggested responses for the text input, override the notification interface controller’s suggestionsForResponseToActionWithIdentifier:forNotification:inputLanguage: method and return an array of strings. When the user selects the associated action, watchOS presents these strings as suggestions. For more information about implementing your notification interface controller, see WKUserNotificationInterfaceController Class Reference.