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.

  • Shadowfax

    Could you please shed some light on how the interaction between iPhone and Apple watch happens ? In the sense that is there any way to update the UI of iPhone app through any touch/gesture action on the Apple watch?I’m not able to find many resources online in this regard

    • The Apple Watch cannot open an iPhone app. But you can share data between the two, so if your watch updates your data source, you have your iPhone app refresh when it’s loaded again with the new data. Take a look at this code example from sharing info between your iPhone app and your Watch:

  • PremKumar

    Please give this source code. I can’t open Notification Screen

  • MK

    Not able to run this examples, can you help me to run this?

    • MK

      Getting Black Screen

  • Narasimhaiah Kolli

    Thank you Madam.Why do we need to edit scheme for notificaiton adn glance??

  • jfloresfont

    Hi Natasha,

    Thanks for your tutorial, it is very useful. Just a question:
    on 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.

    if I click on any button, it raises the method (on the main view controller):

    – (void)handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)remoteNotification

    If I click on the notification (not on the buttons) which method is called? The app is not opened.

    Imagine that I have notification A and B. A raises the view Controller VA and B , VBA. Is it possible to do this just tapping on the notification, without adding any button?

    Regards, Javier.

  • Stephen

    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…

    How does the iOS determine this? In what instances will the notification go to iWatch if it is a local notification?

    • Issac

      Hi Stephen the Notifications are decided, whether the User wear the Watch or not if yes and it’s in touch with skin Notification goes on Watch otherwise on iPhone & same as with Remote notifications.

  • Aslı Sabancı

    I was wondering the same thing as Stephen. I’d like to subtly notify the user with a local notification, not a remote one. Any ideas how to know if this local notification will go to the watch and cause a small vibration or a sound?

    • Vinayak Badrinathan

      I was able to see the local notification by doing the following:
      – ask for sound permission for user notification settings
      – add the default sound to the notification
      – add a category to the notification
      – other required fields too: (title, body, fire date)

  • Aslı Sabancı

    @disqus_N7nizwRCiD:disqus I looked into this in more detail and the same question is asked on the Apple Dev Forums, too and it’s still ambigious. Check this out if you’re interested:

  • John Gambrell

    Hey Natasha, thanks for the tutorial as it exactly what I needed. Have you tried to run it in Xcode 6.2 beta 5? In my app the handle notification method is not being called on clicking the action button. Running your app is doing the same thing so I’m thinking it’s a bug with beta 5.

    • Redge

      I’m having the same problem. I’m on Xcode 6.3.2. Have you found a solution?

  • Stephen

    Thanks @gosalyn:disqus! Yeah it does seema bit ambigous.

    @natashatherobot:disqus Another question is, Right now if we want actionable notifications, we have to provide the field as “Watchkit Simulator Actions” in the JSON payload.

    Is this actually going to be the name of the field for the real device? It seems “Watchkit Simulator Actions” is only going to work for the simulator, while the real device is going to expect something like “Watchkit Device Actions” ? There is very little documentation on this, do you have any ideas?

  • Christian

    Thanks for the post. Very helpful. I was wondering, if it is possible to change the style of those action buttons. like adding an image to it, changing background color or border. And if this could be dynamic on a dynamic notification.

  • Martin Firth

    Can you test whether your notification is working in the simulator?

    • Samhan Sal

      Yup there seems to be some issue with Xcode !
      Try using Xcode 6.2

  • Samhan Sal


    My custom notification button is disabled. Any idea why ?

  • rahul

    Hi natasha
    how to send local notification not remote one . please give me any idea thanks in advance.

  • Min Soe Zan

    Can we change the buttons color of the notification ?

  • Min Soe Zan

    Can we change the button color ?

  • Adriana Pineda

    Hi! I’m testing remote notifications. However I’m not able to get the notification in my apple watch, just in my iPhone. Can you please guide me on how to test remote notifications on my watch? Thanks!

  • Rhodesie


    I was wondering if anyone has been able to test sending a local or remote notification from iOS to the Watchkit? I know the documentation states that this can’t be done and only to use the notification file for notifications, but I thought maybe someone has a work-around?

  • Jeeth

    Hi , i am testing remote notiifcations; i do have action button in my UI. How to add icon before the button?

  • Karthik Mitta

    Did Local notifications fired in iphone will take dynamic interface controller in watch. Because for me it’s always taking static notification controller.

    • edgardoagno

      Hi Karthik, did you manage to show dynamic interface controller for local notifications? If so how did you manage to do it? Thanks!

  • Jacky Coolheart

    what if the notification is from the remote server ? how to set the action and how to listen to it ? On my case, ‘handleActionWithIdentifier’ is not executed on NotificationController (WatchOS)


    Hi, about background images. When I try the app on the device (Apple Watch) , my background image dissapear, on the simulator works fine. Any ideas?

    • Peter Easton

      when you drag the image into your project make sure you check the watch targets

  • Srinivas Appvolutiontech

    Hey Natasha
    how to send Local notifications when apple Watch app in Background.Please give me replay..