Article

Enabling Interactive Notifications

Define a dynamic notification controller that responds to user interactions.

Overview

In watchOS 5, you can define a dynamic interactive notification controller for a notification category. The dynamic interactive notification controllers support interactive UI elements, such as buttons or switches, which you can connect to action methods in your notification controller class.

Add a Dynamic Interactive Interface to Your WatchKit Storyboard

In the project navigator, select your WatchKit app’s storyboard. If your storyboard does not already have a notification interface controller, click the Add button (+) in the toolbar, and drag a Notification Interface Controller onto the canvas.

A screenshot showing the Notification Interface Controller in the Object Library.

Dragging out the notification controller adds a static interface to the storyboard.

A screenshot showing the static notification interface controller in the storyboard.

Next, in the document outline, select the static interface’s Notification Category.

A screenshot showing the Notification Category in the document outline.

In the Attribute inspector, make sure to select both the Has Dynamic Interface and the Has Interactive Interface attributes. You can also customize the notification category name by editing the value in the Name field.

A screenshot showing the required attributes for enabling an interactive controller.

Checking the Has Dynamic Interface and Has Interactive Interface attributes adds the corresponding scenes to the storyboard.

A screenshot showing the dynamic interactive interface on the storyboard canvas.

In watchOS 5, the system uses only the static and interactive interfaces. If you plan to support watchOS 4 and earlier, you still need a dynamic interface.

For more information on handling notifications in watchOS, see Notification Essentials.

Configure the Interactive Interface

After adding the dynamic interactive interface to your storyboard, you must configure it before you can attach its controls to actions. Start by selecting the Dynamic Interactive Notification Controller. In the Identity inspector, set the notification controller’s class.

A screenshot showing the Identity inspector, with the NotificationController class set.

You can now add interactive elements like buttons or switches to the dynamic interactive interface, and draw connections between the interactive controls and action methods in your notification controller.

A screenshot showing the connection between a button in the storyboard and an action method in the navigation controller class.

Note that the action method runs within your notification controller’s context. The notification controller does not have direct access to your complete watchOS app.

Tasks that action methods can perform include:

In general, keep your action methods simple. Complex, multi-step tasks are not a good fit for interactive notifications.

Choose Between Action Methods and Notification Actions

An action method is a method in your notification controller that you connected to an interactive UI element in your storyboard. You typically use these methods to update your notification’s appearance. For example, when the user taps a button, the system calls the button’s action method. You can use this method to show or hide additional information within the notification.

Notification actions are the buttons displayed at the bottom of the notification (for example, Dismiss). When tapped, these buttons dismiss the notification, and the action is forwarded to either your watchOS or iOS app. For more information, see Configuring Actionable Notifications Using Categories.

In general use:

  • Action methods to perform tasks within the notification itself.

  • Notification actions to pass control back to your app and process the action there.

See Also

Notifications

class WKUserNotificationInterfaceController

An interface controller object that manages a dynamic user interface for a local or remote notification.