Define a dynamic notification controller that responds to user interactions on watchOS.
In watchOS 5 and later, 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.
The dynamic interactive interfaces and actionable notifications both let users interact directly with notifications; however, they play somewhat different roles. Action methods perform tasks within the notification controller, while notification actions pass control back to your app.
Dynamic interactive interfaces use the target-action design pattern to connect UI elements in the storyboard to your notification controller’s action methods. You typically use action 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.
An actionable notification, on the other hand, has one or more actions associated with it. The system displays a button for each action beneath the notification. When tapped, these buttons dismiss the notification, and the system passes control back to either your iOS or watchOS app. By default, your app handles these actions in the background; however, you can configure notifications to launch your app to the foreground. For more information, see Adding Actions to Notifications on watchOS.
Add the Interface to Your WatchKit Storyboard
To add a dynamic interactive interface, select your WatchKit app’s storyboard in the Project navigator. 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.
Dragging out the notification controller adds a static interface to the storyboard.
Next, in the document outline, select the static interface’s Notification Category.
In the Attributes 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.
Checking the Has Dynamic Interface and Has Interactive Interface attributes adds the corresponding scenes to the storyboard.
In watchOS 5 and later, if the app has a dynamic interactive interface, the system loads the interactive interface instead of the dynamic interface; however, you need both interfaces if you plan to support watchOS 4 and earlier.
For more information on handling notifications in watchOS, see Adding Notifications to Your watchOS App.
Configure the 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.
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.
Action methods can perform the following tasks:
Update—or even reload—the notification’s user interface.
Perform the notification’s default action (see the
Notification Default Action
Dismiss the notification (see the
In general, keep your action methods simple. Complex, multi-step tasks are not a good fit for interactive notifications.