Class

WKUserNotificationInterfaceController

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

Declaration

@interface WKUserNotificationInterfaceController : WKInterfaceController

Overview

Apps that support notifications can define one or more subclasses of WKUserNotificationInterfaceController and use them to implement their dynamic notification interfaces. For example, you might use a dynamic interface to display custom data from the notification payload or add related graphics.

To create the custom notification interface, add a notification interface controller to your storyboard. Interface Builder provides you with a static interface and you can add a dynamic interface as needed. Set the class of the dynamic interface controller to the name of your WKUserNotificationInterfaceController subclass.

Apps can include multiple notification interfaces in their storyboard file, and each interface is associated with a different category. Categories define the purpose of an incoming notification and are custom to your app. In Interface Builder, specify the category information for each of your notification interfaces using the notification category object attached to the static notification interface controller. When sending notifications to a user, add the appropriate category string to the remote notification payload or set the string in the categoryIdentifier property of a local notification.

After initializing your interface controller, WatchKit calls the didReceiveRemoteNotification:withCompletion: or didReceiveLocalNotification:withCompletion: method to provide you with the payload data from the notification. Your implementations of those methods should update any interface objects and call the provided completion handler as quickly as possible. If you do not call the completion handler in a timely manner, WatchKit displays your static notification interface instead.

Actionable Notifications

For each category your app supports, you can also register actions for that category. When a category has registered actions, WatchKit adds a button for each action to the corresponding static or dynamic notification interface. (Because the buttons are added automatically, do not add them yourself to your custom notification interface.) When the user taps a button, the system forwards the action information to either your WatchKit extension or your iOS app. WatchKit always forwards background actions to your iOS app and always tries to forward foreground actions to your WatchKit extension, falling back to the iOS app as needed.

When the user chooses a foreground action, WatchKit calls the handleActionWithIdentifier:forRemoteNotification: or handleActionWithIdentifier:forLocalNotification: method of your app’s extension delegate. (For actions that include a text response from the user, WatchKit calls the handleActionWithIdentifier:forRemoteNotification:withResponseInfo: or handleActionWithIdentifier:forLocalNotification:withResponseInfo: method instead.) If your delegate does not implement the appropriate method, WatchKit calls the handleActionWithIdentifier:forRemoteNotification: or handleActionWithIdentifier:forLocalNotification: method of your app’s main interface controller instead.

Interface Builder Configuration Options

Xcode lets you configure information about your notification interface controller in your storyboard file. A notification interface controller supports almost all of the attributes associated with its parent class plus those in Table 1.

Table 1

Notification interface controller attributes

Attribute

Description

Has Dynamic Interface

A checkbox indicating whether a dynamic interface is supported for notifications of this type. Dynamic interfaces are displayed whenever possible, but WatchKit may fall back to using your static interface because of power restrictions or when your WatchKit extension does not respond in a timely manner.

Apple Watch always displays the static interface in Notification Center.

The notification category object associated with your notification interface controllers also contains configurable attributes. Table 2 lists the attributes of the notification category object and their meaning.

Table 2

Notification category attributes

Attribute

Description

Name

The name of the category that this interface supports. For local notifications, this value is corresponds to the string in the categoryIdentifier property of the UNNotificationContent object. For remote notifications, it is the string in the category key in the payload. When a notification arrives, WatchKit uses the category string in the notification to decide which of your interface controllers to display.

Sash Color

The color to apply to the sash at the top of the long look notification interface.

Wants Sash Blur

A checkbox indicating whether the sash includes a blur effect over the background.

Title Color

The color to apply to the text displayed in the sash.

Description

The format string to display when multiple notifications of the same type arrive simultaneously. If you specify a custom string, you can use the %d variable to reflect the number of notifications. If you do not specify a custom string, WatchKit uses the string %d Notifications to reflect the number of notifications that arrived.

Has Dynamic Interface

A checkbox indicating whether a dynamic interface is supported for notifications of this type. Dynamic interfaces are displayed whenever possible, but WatchKit may fall back to using your static interface because of power restrictions or when your WatchKit extension does not respond in a timely manner.

Apple Watch always displays the static interface in Notification Center.

Topics

Initializing the Interface Controller

- init

Initializes and returns the interface controller using the specified remote notification data.

Processing the Notification

- didReceiveNotification:

Delivers a notification object to your interface controller for processing.

- didReceiveNotification:withCompletion:

Delivers a notification object to your interface controller for processing.

Deprecated

Working with Actions

notificationActions

The actions associated with the current notification.

- performNotificationDefaultAction

Launches the watchOS app and performs the current notification’s default action.

- performDismissAction

Dismisses the notification interface controller.

- dismissController

Dismisses the notification interface controller.

Deprecated

Offering Suggestions for Text Input

- suggestionsForResponseToActionWithIdentifier:forNotification:inputLanguage:

Returns an array of attributed strings representing the text suggestions to display during text input.

Constants

WKUserNotificationInterfaceType

The type of notification interface to display.

Relationships

See Also

Notifications

Enhancing Your watchOS App with Notifications

Alert the user of significant events with notifications even when your app is not running.