Article

Enhancing Your watchOS App with Notifications

Alert the user of significant events with notifications even when your app is not running.

Overview

Local and remote notifications let you communicate with the user even when your app is not running. Your app can schedule local notifications directly in your watchOS app, or in the companion app on iPhone. Specify a time or a location to trigger the notification’s delivery. Alternatively, you can send remote notifications from your server to the user’s iPhone using the Apple Push Notification service (APNs).

The system automatically forwards notifications to Apple Watch, even if you do not have a watchOS app; however, you can customize the notification support provided by your watchOS app to improve the user experience.

Specifically, your watchOS app can:

  • Respond to the delivery of local or remote notifications.

  • Add support for actionable notifications.

  • Provide custom long-look interfaces for notifications.

  • Enable interactive long-look notification interfaces.

  • Schedule local notifications directly from your watch

Use the UserNotifications framework to schedule local notifications, and to handle both local and remote notifications.

Request Permission to Use Notifications

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.

To request authorization:

  1. Access the shared UNUserNotificationCenter object by calling the current() class method.

  2. Call the notification center’s requestAuthorization(options:completionHandler:) method. You must call this method before performing any operations that involve local or remote notifications.

For example, you might call requestAuthorization(options:completionHandler:) during your app’s launch cycle. The first time the user launches either your watchOS or iOS app, this method prompts them to grant authorization. After the user responds to this prompt, subsequent launches of either app won’t prompt them again. However, users can always change their authorization in the Settings app.

For detailed instructions, see Asking Permission to Use Notifications.

Start with the Short-Look Interface

When the Apple Watch displays a notification, the system first presents the short-look interface (see Figure 1).

Figure 1

Short-look interface

A screenshot of the short look interface, with the icon, title and app name called out.

The short-look interface is a nonscrolling screen that the system creates automatically. You cannot customize this interface. The system uses a template to display the app name and icon along with the title string from the notification payload. For local notifications, you specify the title string using the UNMutableNotificationContent object’s title property. For remote notifications, you specify it using the alert dictionary’s title key inside the notification’s payload.

Transition to the Long-Look Interface

If the user continues to look at the notification, the system transitions quickly from the short-look interface to the long-look interface (see Figure 2).

Figure 2

Long-look interface

A screenshot of the short look interface, with the sash, content, actions, and dismiss button called out.

The long-look interface is a scrollable screen that displays the notification’s content and any associated action buttons. The system’s default long-look interface includes your app icon, the notification’s title string, and the alert message; however, your app can customize this interface.

The long-look notification includes the following sections:

  • The sash is an overlay that contains the app icon and app name. The system automatically generates the sash, but you can configure its appearance using the notification category’s attributes. In the storyboard, select the arrow that points to the static interface, then set the desired attributes in the Attributes inspector.

  • The content area contains detailed information about the incoming notification. For information on customizing the long-look interface, see Customizing Your Long-Look Interface.

  • If you provide a dynamic interactive interface for the notification, the content area can contain controls, like buttons or switches. For more information, see Adding Interactive Controls to a Long-Look Interface.

  • The bottom contains a Dismiss button and any registered action buttons. For more information, see Adding Actions to Notifications on watchOS.

By default, the system dismisses the long-look interface, launches your app, and calls your notification center delegate’s userNotificationCenter(_:didReceive:withCompletionHandler:) method whenever the user taps the notificaiton. The response parameter’s actionIdentifier property varies, as shown in Table 1.

Interface element

Action identifier

Action button

The identifier for the selected action.

Dismiss button

UNNotificationDismissActionIdentifier

Anywhere else

UNNotificationDefaultActionIdentifier

For dynamic interactive interfaces, tapping the app content does not launch your watchOS app. Instead, the user can interact with any controls placed in the interface, and the system calls the corresponding; action method. The system only dismisses the notification and launches your app if the user taps the app icon or sash, or if you explicitly call the notification controller’s performNotificationDefaultAction() method.

Group Notification Threads

On watchOS 5 and later, the system groups related notifications together in the Notification Center. You can control how watchOS groups your app’s notifications by adding a thread ID. The system automatically groups notifications with the same category and thread ID as they arrive. For local notifications, set the content’s threadIdentifier property. For remote notifications, use the thread-id key.

Additionally, your dynamic long-look interface can respond to grouped notifications, letting it display content from multiple notifications within a single long-look interface. To receive information from multiple notifications, select the notification category in the storyboard, and enable Handles Grouping in the Attribute inspector (Figure 3).

Figure 3

Enable the Handles Grouping attribute

A screenshot showing the Notification Category’s attributes in the Attributes inspector, with Handles Grouping enabled.

With Handles Grouping enabled, if a dynamic long-look interface is on screen and a new notification with a matching category and thread ID arrives, the system calls your interface controller’s didReceive(_:) method again. Your implementation must be prepared to append the incoming content to the existing interface. For example, if the interface controller displays the content in a table view, you can add a new row for the incoming content.

Handle Notifications in Your App

If your Watch app is running on screen, or is the frontmost app when a notification arrives, the system calls the userNotificationCenter(_:willPresent:withCompletionHandler:) method on your notification center delegate. The value you pass to the completion handler determines how the system responds.

  • Pass UNNotificationPresentationOptionNone to silence the notification.

  • Otherwise, the system presents the notification using the specified options.

  • If you do not implement the userNotificationCenter(_:willPresent:withCompletionHandler:) method, the system silences the notification and doesn’t deliver it to your Watch app.

Understand Notification Forwarding

Apple Watch and iPhone work together to deliver notifications. Instead of appearing on both devices, notifications appear only on the device that is most likely to have the user’s current focus. The system decides which device receives the notification based on the notification’s type, on which process created the notification, and on which device is active (see Table 2).

Table 2

Notification delivery

Notification type

Source

Destination

Local

iOS app

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

Local

WatchKit extension

Apple Watch only

Remote

Your server

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

Silent

Your server

iPhone only

If a notification can be delivered to either device, the system uses the devices' locked state to determine the best destination.

The following rules are checked in order:

  1. If the user’s iPhone is unlocked and the screen is on, notifications go to the phone.

  2. Otherwise, if the Apple Watch is on the user’s wrist and unlocked, notifications go to the watch.

  3. Otherwise, notifications default back to iPhone.

Also, if the user has more than one Apple Watch, local notifications only appear on the device that scheduled it.

Topics

Custom Interfaces and Actions

Customizing Your Long-Look Interface

Create custom interfaces for your watchOS app’s notifications.

Adding Interactive Controls to a Long-Look Interface

Define a dynamic notification controller that responds to user interactions on watchOS.

Adding Actions to Notifications on watchOS

Use actionable notifications to provide a set of responses for the notification.

Testing

Testing Custom Notification Interfaces

Test your notification interfaces on watchOS using a notification scheme and payload file.