Create custom interfaces for your watchOS app’s notifications.
To customize the appearance of your app’s notifications, you can provide up to three versions of the long-look interface:
(Required.) A static interface that you create at design time. The interface can contain placeholders for the notification title, subtitle, and alert message, plus any static images or text that you specify.
(Optional.) A dynamic interface that you can configure at runtime based on the notification’s payload. In dynamic interfaces, you can modify the text or images that are displayed, as well as add other noninteractive elements, like showing a location on a map view.
(Optional.) A dynamic interactive interface that contains controls like buttons or switches. Like the dynamic interface, you can configure this interface at runtime. It also lets the user interact directly with the notification.
When a notification arrives, watchOS chooses whether to display your static or dynamic interface based on several factors. watchOS displays the static interface when:
A dynamic interface is not available.
The device does not have enough power to warrant displaying the dynamic interface.
You explicitly tell watchOS not to display the dynamic interface.
In all other cases, watchOS displays one of your dynamic interfaces. On watchOS 5 and later, the system loads the dynamic interactive interface, if one is available. Otherwise, it loads the regular dynamic interface.
After selecting the correct interface, watchOS loads the appropriate storyboard resources and prepares the interface as shown in Figure 1.
For dynamic interfaces, the system instantiates a notification interface controller for your interface. This controller works exactly like any other interface controller in your app—with one extra step. While loading, the controller processes the notification payload, giving you an opportunity to configure your interface based on the notification’s content.
Add the Desired Interfaces to the Storyboard
When you create a new WatchKit App project, or add a WatchKit App template to an existing project, Xcode adds notification scenes by default. This includes adding a static interface, a dynamic interface, and a dynamic interactive interface to the storyboard.
You can drag additional notification interface controllers from the library to the storyboard. In this case, Xcode only adds the static interface. You can add the dynamic interface by selecting the static interface, and checking the Has Dynamic Interface checkbox in the Attributes inspector. By default, this adds both the dynamic interface and a dynamic interactive interface. If you don’t intend on adding controls to the notification, uncheck the Has Interactive Interface checkbox to remove the interactive version.
Figure 2 shows the unmodified notification interfaces in the storyboard.
Configure the Notification Category
Next, specify the notification category for the entire set of interfaces, as shown in Figure 3.
Select the arrow that points to the static interface.
In the Attributes inspector, enter the name of the notification category as the Name attribute.
When transitioning to a long-look interface, watchOS looks at the notificaiton’s category, and loads the corresponding long-look interface. Create separate interfaces for each category you intend to support.
Design a Static Interface
Use the static notification interface to define a simple version of your custom notification interface. If the only elements that change are your notification’s title, subtitle, and alert text, then you only need the static interface. The static interface also provides a fallback in case your app can’t configure the dynamic interface in a timely manner.
The following limitations apply to static notification interfaces:
Store all images in the WatchKit app bundle.
The interface can’t include controls, tables, maps, or other interactive elements.
The interface provides three outlets that you can connect to labels:
notification. The system automatically sets the text of labels connected to these outlets based on the notification’s payload.
All other labels must use static text that is set at design time. The text can’t change.
Figure 4 shows a simple example. The system automatically sets the icon and app name. The body contains three labels: <Title>, <Subtitle>, and <Alert>. These labels are connected to the
notification outlets respectively. The system sets their content at runtime.
Design a Dynamic Interface
A dynamic notification interface lets you provide a richer notification experience for the user. With a dynamic interface, you can configure the interface’s content at runtime. This lets you process the notification’s payload, and highlight important information from the notification.
The dynamic interface can only contain noninteractive elements, like text, images, or showing a location in a map view. If you want to add interactive controls, for example buttons or switches to show or hide additional information, then you need a dynamic interactive interface (see Adding Interactive Controls to a Long-Look Interface).
Like the static interface, you still have access to the
notification outlets. Unlike the static interface, the dynamic notification interface must be associated with a custom
WKUser subclass. This lets you define your own outlets, and gives you a chance to process the notification data and update your interface at runtime.
In most ways, you create your dynamic interface much as you would any other scene for watchOS, but unlike regular scenes, the dynamic interface cannot include interactive controls. Instead, tapping the notification launches your app.
When designing a dynamic notification interface:
Use labels, images, groups, and separators to build the bulk of your interface.
Include tables and maps only as needed.
Do not include buttons, switches, or other interactive controls.
You can use SpriteKit scenes, SceneKit scenes, or inline videos to produce visually rich notifications.
Figure 5 shows a simple example. Like the static interface, the system automatically sets the icon and app name. Also, the body contains the <Title>, <Subtitle>, and <Alert> labels connected to the
notification outlets respectively. While the <date> and <time> labels are connected to new outlets. The controller sets their value after analyzing the notification’s content. Finally, the Date: and Time: labels are static, and don’t change.
When transitioning to a dynamic long-look interface, watchOS loads the corresponding scene from your storyboard, and instantiates your
WKUser subclass. After initializing the interface controller, watchOS calls
did and passes the notification. Figure 6 shows the steps that watchOS takes to prepare your interface.
did method to set up your user interface based on data from the notification. Do not perform long tasks, like downloading additional data, in this method. If the method takes too long to return, the system may default to the static interface.