Customizing Your Long-Look Interface

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.

Figure 1

Loading the notification interface

An illustration showing how the system loads static and dynamic interfaces.

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.

Figure 2

The static, dynamic, and dynamic interactive interfaces

A screenshot showing the unmodified notification interfaces in the storyboard’s canvas.

Configure the Notification Category

Next, specify the notification category for the entire set of interfaces, as shown in Figure 3.

  1. Select the arrow that points to the static interface.

  2. In the Attributes inspector, enter the name of the notification category as the Name attribute.

Figure 3

Setting the notification category

A screenshot showing the notification category’s 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: notificationTitleLabel, notificationSubtitleLabel, and notificationAlertLabel. 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 notificationTitleLabel, notificationSubtitleLabel, and notificationAlertLabel outlets respectively. The system sets their content at runtime.

Figure 4

A static interface in the storyboard

A screenshot showing a static notification interface in the storyboard.

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 notificationTitleLabel, notificationSubtitleLabel, and notificationAlertLabel outlets. Unlike the static interface, the dynamic notification interface must be associated with a custom WKUserNotificationInterfaceController 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 notificationTitleLabel, notificationSubtitleLabel, and notificationAlertLabel 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.

Figure 5

A dynamic interface in the storyboard

A screenshot showing a dynamic notification interface in the storyboard.

When transitioning to a dynamic long-look interface, watchOS loads the corresponding scene from your storyboard, and instantiates your WKUserNotificationInterfaceController subclass. After initializing the interface controller, watchOS calls didReceiveNotification: and passes the notification. Figure 6 shows the steps that watchOS takes to prepare your interface.

Figure 6

Loading and configuring a dynamic interface

A figure showing the steps that the system performs while loading a dynamic notification interface.

Implement the didReceiveNotification: 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.

See Also

Custom Interfaces and Actions

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.