WatchKit: Actionable Notifications

Notifications on Apple Watch facilitate quick, lightweight interaction in two parts: the Short Look and the Long Look. A Short Look appears when a local or remote notification needs to be presented to the user. A Short Look provides a discreet, minimal amount of information—preserving a degree of privacy. If the wearer lowers his or her wrist, the Short Look disappears. A Long Look appears when the wearer’s wrist remains raised or the user taps the short look interface. It provides more detailed information and more functionality—and it must be actively dismissed by the wearer. – Apple Watch Human Interface Guidelines

So if you’re still confused about how Notifications work on the Apple Watch, it goes like this:

  1. iPhone or Apple Watch – iOS decides whether it is appropriate to display the notification on the iPhone or Apple Watch. Given the notification will be displayed on the Apple Watch…
  2. Subtle Notification – the user is subtly notified (likely via some kind of  vibration) to let them know there’s a new notification
  3. Abbreviated Notification – if the user raises her wrist, she’ll see a Short Look notification. This is essentially the app icon, app name, and the title of the notification
  4. Detailed Notification – if the user taps on the Short Look notification or continues looking at her wrist, she’ll see the Long Look notification. This is the notification that you get to customize!
  5. User Action – The user can dismiss the notification or act on it by tapping an available action button (if any) or by launching your app

So the only part you have to worry about for customization is the Long Look Notification Interface, which is what I’ll cover in this post.

Setup Project

Follow the steps from my “Hello World” WatchKit Tutorial to get started. The only difference is that when you get to the part when you’re creating the Watch App Target, check the Include Notification Scene check box:


Take a look at Interface.storyboard. You’ll notice that you now have a Static and Dynamic notification interface:

Notification Interface

The Static Interface is a simpler interface that contains only the notification’s alert message and any static images and text that you configure at design time.

The Dynamic Interface displays a fully customized version of the notification’s content, and can include custom content and graphics provided by your WatchKit extension. Note that your NotificationController is mapped to the Dynamic Interface. Meanwhile, you cannot change the Class of your Static Interface (it can only be configured in the storyboard)!

The Static Scene is required, but you can delete the Dynamic Scene if you’re not using it.

Setup Notification Scheme

If try running the Watch App at this point, you will see the app, not the notification. To test your notification interface, you have to Duplicate your Watch App Extension Scheme, and run the new scheme:

Now you might wonder where all the data for my notification came from! No, it’s not magic. By checking the box to include the Notification Interface in your Watch App, it automatically created a PushNotificationPayload.json file for you with some test data.

Notification Payload

Change the alert message and the First Button title and re-run the app to see the content change!


The notification interface is pretty limited for customization. Here are a few items for your designers to customize:

The Watch App Icon

There are now many new icon sizes that are necessary for the Watch App:

Notification Icon

Notice that your app icon will be cropped into a circle.

The Sash Color

I was really confused by the terminology here, but the Sash really stands out once you change it’s color…

Sash Color

As a non-designer, I would recommend keeping the Sash it’s default transparent color. But I’m sure your designer can come up with a decent color combination that works well if needed!

Wrap Text

If you’ve worked with UILabels, you probably already know this trick, but this is a reminder to remember to wrap your text:

Watch Lines 0

This is especially important to remember for the Watch, since the screen is tiny compared to everything we’re used to!

Display Name

Again, since the Watch is so tiny, you might want to display your app name differently (e.g. American Airlines might want to change their name to AA).

Bundle Display Name

Background Image

You can use a background Image instead of just the color for your message content:

Background Image Watch Notification


Remember, notifications are NOT interactive (Glances aren’t either). If you do try to put an interactive item on your Notification, your app will not build!

Notification Button Bad

The only interaction your Notification will have is via the Action Buttons that are specified in your JSON Payload!


Since I’m not a designer, I now want to take a look at the beautiful American Airline app that is features on Apple’s official WatchKit page:

American Airlines

You can make this exact interface:

  • They have a custom Watch App Icon
  • They’re using the default Transparent Sash
  • The Alert text is wrapped (by setting number of lines to 0)
  • The Display Name is American
  • There is a Background Image of wings as the background for the notification
  • The Action Button (Trip Details) comes from their JSON Notification payload

So how do you handle the button actions? It’s simple…

Handle Notification Actions

Let’s say that when the Villain from Despicable Me taps on his notification about Minions, he wants to see an image in the Watch App. So my Watch App Interface will be very simple:


Now, in my InterfaceController, I can implement the handleActionWithIdentifier:forRemoteNotification: method:

handleaction interfaceController

So now when the Villain clicks the “Show Minions!” button (with identifier “showMinionsButtonAction” as specified in the JSON payload) on the notification, he’ll be taken to the app to see his Minions playing golf!

Dynamic Notifications

Throughout this tutorial, so far I’ve been using the Static Notification Interface. How do you trigger the Dynamic one if you need more customization? Remember that I mentioned that the Dynamic Interface is tied to the NotificationController:

Dynamic Notification

So you guess it! The answer is in the NotificationController. Just comment out the code that’s already there, and make sure to use the .Custom completionHandler!


That’s it! You are now triggering the  Dynamic Notification Interface!

It’s that simple! You’re now all set up to create your own custom notifications!

Enjoy the article? Join over 20,000+ Swift developers and enthusiasts who get my weekly updates.