Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Managing a Custom Long Look Interface

The custom long-look notification interface consists of two separate interfaces: one static and one dynamic. The static interface is required and is a simple way to display the notification’s alert message and any static images and text that you configure at design time. The dynamic interface is optional and gives you a way to customize the display of your notification’s content at runtime.

When you add a new notification interface controller to your storyboard file, Xcode creates both the static and dynamic interfaces. You can remove the dynamic interface by selecting the static interface, and unselecting the Has Dynamic Interface checkbox in the Attributes inspector. Figure 20-1 shows both the unmodified static and dynamic interface scenes from a storyboard file. The static and dynamic scenes are associated with the same notification type, which you configure using the notification category object attached to the static scene.

Figure 20-1Static and dynamic notification interfaces image: ../Art/notification_static_dynamic_2x.png

When a notification of the correct type arrives, watchOS chooses whether to display your static or dynamic interface based on several factors. watchOS automatically displays the static interface in Notification Center, when a dynamic interface is not available, when there is not enough power to warrant displaying the dynamic interface, or when you explicitly tell watchOS not to display the dynamic interface. In all other cases, watchOS displays your dynamic interface. After making the choice, watchOS loads the appropriate storyboard resources and prepares the interface as shown in Figure 20-2. The loading process for the dynamic interface is mostly the same as for your app’s other interface controllers, with the exception of processing the notification payload, which is specific to notification interface controllers.

Figure 20-2Preparing the notification interface image: ../Art/notification_process_2x.png

Adding a Custom Notification Interface to Your App

When creating the Watch app target for your app, the Include Notification Scene option is selected by default, and Xcode provides you with an empty storyboard scene and a custom subclass to use for your notification interface controller. If you disable this option when creating your target or if you need to create additional notification interfaces, you can create the notification interface later.

To create a new notification interface, drag a notification interface controller object to your storyboard file. The new interface contains only the static interface controller initially. To add a dynamic interface, you must perform some additional configuration steps.

Configuring a dynamic notification interface controller
  1. In your project, create a new WKUserNotificationInterfaceController subclass.

    Create the new source file and add it to your WatchKit extension target. Give your subclass an appropriate name that distinguishes it from your other notification interface controllers.

  2. Enable the Has Dynamic Interface attribute of the notification category. This step adds the dynamic scene to your storyboard file.

  3. Set the class of your dynamic notification interface controller to the class you created in Step 1.

Apps may have multiple notification interfaces, but the category for each interface must be unique.

Configuring the Category of a Custom Interface

Each notification interface must have an assigned notification category that tells Apple Watch when to use it. Incoming notifications can include a category key in their payload, the value of which is a string you define. Apple Watch uses the category name to decide which of your notification scenes to display. If an incoming notification does not include a category string, Apple Watch displays the notification interface configured with the default category.

To assign a notification type to your notification interface, select the Notification Category object in your storyboard and go to the Attributes inspector, shown in Figure 20-3. Enter the category name in the Name field of the inspector. You can also set the sash color and title text color for your custom interface in the inspector.

Figure 20-3Configuring the notification type information image: ../Art/notification_category_config_2x.png

When generating remote notifications, your server specifies the notification type by including the category key in the aps dictionary of the payload. For local notifications, you specify this value in the categoryIdentifier property of the UNMutableNotificationContent object.

Configuring a Static Notification Interface

Use the static notification interface to define a simple version of your custom notification interface. The purpose of a static interface is to provide a fallback interface in the event that your WatchKit extension is unable to configure the dynamic interface in a timely manner. The interface is also displayed in Notification Center. The rules for creating a static interface are as follows:

  • All images must reside in the Watch app bundle.

  • The interface must not include controls, tables, maps, or other interactive elements.

  • The interface’s notificationAlertLabel outlet must be connected to a label. The label’s contents are set to the notification’s alert message. The text for all other labels does not change.

Figure 20-4 shows the configuration of the static and dynamic scenes for a custom notification interface in a calendar app. The notification arrow points to the static scene, which contains a custom icon and two labels. In the static interface, the label containing the string <message> is the one associated with the notificationAlertLabel outlet and therefore receives the notification’s alert message at runtime.

Figure 20-4Static and dynamic scenes for a single notification type image: ../Art/notification_design_2x.png

Configuring the Dynamic Notification Interface

A dynamic notification interface lets you provide a more enriched notification experience for the user. With a dynamic interface, you can display more than just the alert message. You can incorporate additional information, configure more than one label, display dynamically generated content, and so on.

To implement a dynamic notification interface, you must create a custom WKUserNotificationInterfaceController subclass. How you implement that subclass determines what information is displayed in the notification interface.

Designing Your Dynamic Interface

Configure your dynamic interface as you would any other interface controller scene. Include outlets in your subclass to refer to labels, images, and other objects in the scene, and use those outlets to configure the contents of the scene at runtime. Tapping your notification interface launches the app, so notification interfaces should not contain interactive controls.

  • Use labels, images, groups, and separators for most of your interface.

  • Include tables and maps only as needed in your interface.

  • Do not include buttons, switches, or other interactive controls.

  • Use SpriteKit scenes, SceneKit scenes, or inline videos to produce visually rich notifications.

Configuring Your Dynamic Interface at Runtime

When a notification of the appropriate type arrives, watchOS displays the appropriate scene from your storyboard and asks your WatchKit extension to instantiate the corresponding WKUserNotificationInterfaceController subclass. Figure 20-5 shows the steps that watchOS takes to prepare your interface. After initializing the notification interface controller, watchOS delivers the payload data to it using the didReceiveNotification:withCompletion: method. You use the payload data to configure the rest of your notification interface, after which you call the provided completion handler block to let watchOS know that your interface is ready.

Figure 20-5Configuring the dynamic notification interface image: ../Art/notification_event_cycle_2x.png

Always use the didReceiveNotification:withCompletion: method to configure your notification interface. When implementing the method, execute the provided completion handler as soon as you have configured the interface. If you wait too long, Apple Watch abandons the attempt to display your dynamic interface and displays the static interface instead. If you want watchOS to display your static interface instead, specify the WKUserNotificationInterfaceTypeDefault constant when calling the completion handler.

Testing Your Custom Notifications

When you are ready to test your dynamic interface in the simulator, create a custom build scheme for running your notification interface if you have not done so already. When configuring the interface, specify the JSON data file containing the test data you want delivered to your interface. Xcode provides custom JSON files for specifying this data. For more information, see Specifying a Payload for Remote Notification Testing and Debugging.

On a device, notifications are normally delivered while your Apple Watch is on your wrist and your iPhone is locked. To test your notification interfaces while the device is not on your wrist, do the following:

  • In the Apple Watch app on your paired iPhone, disable the Wrist Detection option. (You can find this option in the General settings.)

  • Make sure your Apple Watch is not on a charging puck.

  • Make sure your iPhone is locked.

For more information about setting up the build schemes and configuring your payload data, see Building, Running, and Debugging Your Watch App.