WKUserNotificationInterfaceController
An interface controller object that manages a dynamic user interface for a local or remote notification.
Declaration
@MainActor class WKUserNotificationInterfaceControllerOverview
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 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 associate each interface 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 didReceive(_:) 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 don’t 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 system automatically adds the buttons, don’t manually add your own to your custom notification interface. For more information about registering actions, see Declaring your actionable notification types.
When the user taps an action button, the system launches your app and calls your notification delegate’s userNotificationCenter(_:didReceive:withCompletionHandler:) method. The response parameter’s actionIdentifier property contains the identifier for the selected action. Implement your delegate’s userNotificationCenter(_:didReceive:withCompletionHandler:) method to check this identifier, and then perform the corresponding task. For more information, see Handling notifications and notification-related actions.
The following rules define where the system handles the action:
The system always handles foreground actions on the device where the user selected the action. For example, if you send a remote notification to the user’s iPhone and the system automatically forwards it to their Apple Watch, tapping the action runs it on the watch.
The system always handles background actions on the device that was the notification’s target. For example, if you send a notification to the user’s iPhone and the system automatically forwards it to their Apple Watch, tapping the action runs it in the background on their iPhone.
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 the following table.
Attribute | Description |
|---|---|
Has Dynamic Interface | A checkbox indicating whether the app supports a dynamic interface for notifications of this type. WatchKit displays dynamic interfaces whenever possible, but WatchKit may fall back to using your static interface because of power restrictions or when your WatchKit extension doesn’t respond in a timely manner. [Image] Apple Watch always displays the static interface in Notification Center. |
The notification category object associated with your notification interface controllers also contains configurable attributes. The following table lists the attributes of the notification category object and their meaning.
Attribute | Description |
|---|---|
Name | The name of the category that this interface supports. For local notifications, this value corresponds to the string in the Categoryidentifier property of the Unnotificationcontent object. For remote notifications, it’s the string in the |
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 |
Has Dynamic Interface | A checkbox indicating whether the app supports dynamic interfaces for notifications of this type. WatchKit displays dynamic interfaces whenever possible, but it may fall back to using your static interface because of power restrictions or when your WatchKit extension doesn’t respond in a timely manner. [Image] Apple Watch always displays the static interface in Notification Center. |