Article

Adding Notifications to Your watchOS App

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 sent to your iOS app to a paired Apple Watch, even if you do not have a watchOS app; however, you can improve the user experience on Apple Watch by customizing the notifications in your watchOS app.

With watchOS 6 and later, you can also send remote notifications, including background updates, directly to Apple Watch. If your watchOS app has an iOS companion, you can send the notification to both devices. The system ensures that the user only receives the notification once, selecting the best option based on the devices' current state.

A watchOS app can customize notifications to:

  • 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.

  • Receive remote notifications directly from your server (watchOS 6 and later).

  • Receive background notifications from your server (watchOS 6 and later).

In your watchOS app, schedule local notifications and handle both local and remote notifications using the UserNotifications framework.

Request Permission to Use Notifications

Before the system can post alerts or play sounds for your app’s notifications, your watchOS 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 can’t 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 when 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

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 watchOS 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.

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

If you send a remote notification to iPhone, it can appear on either Apple Watch or iPhone, depending on the locked/unlocked state of both devices. With watchOS 6 and later, you can also send notifications directly to Apple Watch. These notifications only appear on Apple Watch.

Background

Your server

If you send a background notification to iPhone, the phone always handles the notification. It never forwards background notifications to Apple Watch; however, with watchOS 6 and later you can also send background notifications directly to Apple Watch.

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. Remote and background notifications also only appear at the specified watch—so you may need to send notifications to multiple devices.

Sending Remote Notifications Directly to Apple Watch

With watchOS 6 and later, you can send remote notifications directly to Apple Watch. Before sending a notification, you must register your watchOS app, as described in Registering Your App with APNs. Registering your app creates a unique device token for the watch. Use that token to send notifications directly to the watch.

The recommended notification strategy depends on your watchOS app, as shown in the table below.

Type of app

Notification strategy

Apple Watch-only app

Always send remote notifications to Apple Watch.

Independent watchOS app with an iOS app

Because the app may not be installed on both devices, you should always send the notification to both iPhone and Apple Watch. The system ensures that the user only receives one notification at the best destination.

Dependent watchOS app with an iOS app

You can either send the notification just to iPhone, or send it to both devices. In either case, the system ensures that the user only receives one notification at the best destination.

For more information on watchOS app types, see Creating Independent watchOS Apps.

Send Background Notifications to Apple Watch

You can also use background notifications to silently update your app. The system never forwards background notifications from iPhone to Apple Watch, so you must always send background notifications directly to the device you want to update. For complete instructions, see Pushing Background Updates to Your App.

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.