Haptic feedback with the Taptic Engine - WKInterfaceDevice and WKHapticType in WatchKit and watchOS 2

The Taptic Engine is a game-changing piece of hardware that Apple has added to the Apple Watch. One of the annoyances of Android Wear and Pebble is that the notification vibrations are not very subtle, and everyone nearby knows that your watch demands attention. The Taptic Engine allows you to send taps to your users wrist, feeling much like someone tapping their finger on you, as a subtle and discreet to communication information for users that they can choose to ignore or receive without bothering those around them.

So what the heck is a Haptic and how is it different from a Taptic?

Haptic Feedback used in technology typically refers to any kind of vibration or force used in input devices on the user. Pressing a button on a smooth glass screen just doesn't feel as satisfying as clicking a physical button on a mouse. That's because the mouse button depresses and then gives a 'click' feeling vibrating into your finger to indicate the button has been pressed. What's nice about this is that you can know when a mouse button has been successfully pressed without looking at it.

Compare this to a button on an iOS App, where you have to visually look where you are aiming your finger, and rely on visual feedback that the button has been pressed correctly. Haptic feedback refers to the class of technology to simulate physical feedback in a device, like the vibrations of a Playstation Controller or the taps on an Apple Watch.

The Taptic Engine is Apple's marketing name for the piece of hardware that can produce Haptic feedback by way of the feeling of taps on your wrist in response to different actions in the hardware. It can notify you that you scrolled to the end of a list, it can make it feel clicky as you click through the items of a WKInterfacePicker list, or even indicate on your driving directions if it's time to turn left or right with different feeling taps so you don't even have to look at the Watch screen to know which way to turn.

Coding Your Own Haptics

The API is exceedingly simple, with just a quick API call to playHaptic():

WKInterfaceDevice.currentDevice().playHaptic(.Click)

The playHaptic() API takes in values from the WKHapticType enum.

enum WKHapticType : Int {
    case Notification
    case DirectionUp
    case DirectionDown
    case Success
    case Failure
    case Retry
    case Start
    case Stop
    case Click
}

Apple currently doesn't allow for defining custom Haptic events, so whatever you want to do on your app, you'll have to do it with one of these nine Haptic types.

It's pretty important to understand the feeling, sound and intention of each of these types, so we'll cover each in detail.

WKHapticType in Detail

.Notification

Sound: Chime
Haptic: Tap-Tap-Vibrate

The .Notification type is intended for drawing the user's attention when something significant or out of the ordinary has occurred.

.DirectionUp

Sound: Increasing Pitch
Haptic: Tap-Tap

The .DirectionUp type is intended for indicating a significant increase value threshold has been crossed such as when moving up a list.

.DirectionDown

Sound: Decreasing Pitch
Haptic: Tap-Tap

The .DirectionDown type is intended for indicating a significant decrease value threshold has been crossed, such as when moving down a list.

.Success

Sound: Confirmation Ding
Haptic: Tap-Tap-Tap

The .Success type is intended as a confirmation tone to indicate some action has been completed successfully.

.Failure

Sound: Failure Ding
Haptic: Long Vibrate

The .Failure type is intended as a failure tone to indicate some action has not been completed successfully.

.Retry

Sound: Quick Ding-Ding-Ding
Haptic: Long Vibrate

The .Retry type is intended as a gentle tone to indicate some action has not been completed successfully but the user has an opportunity to retry. Typically you should display some UI with this tone giving the user an opportunity to retry their failed action.

.Start

Sound: Long Ding
Haptic: Long Tap

The .Start type is intended to indicate the start of an activity, such when a timer begins.

.End

Sound: Long Ding-Long Ding
Haptic: Long Tap-Long Tap

The .End type is intended to indicate the end of an activity, such when a timer has ended.

.Click

Sound: Very soft click
Haptic: Light tap

The .Click type is intended to indicate a clicking sound, like when a dial is clicking.

Haptic Demo sample provided on GitHub

Taptic Engine Considerations

The Taptic Engine cannot overlap Haptics, and there is a delay between each one that can be played. So for example, let's say you wanted to play a .Click as you move through each item in a list. If you move quickly through the list, a lot of .Click haptics will be ignored, and your user will find it not feeling quite right when the taps fall out of sync from your UI.

Make sure that when you are designing your application, only use haptics on rare and significant events to both conserve battery as well as feel strange if they are asked to overlap and you end up losing feedback commands that you intended.

Trying It Out

We've provided sample code for an app to try out each of the haptic types on the Sneaky Crab GitHub. Unfortunately, the current version of the watchOS Simulator does not support sounds, so you'll have to install this on your iOS 9/watchOS 2 hardware to try it out.

Remember that it is currently impossible to reverse a watchOS 2 update, so make sure that you only update to watchOS 2 for test devices and not your main Apple Watch, especially considering that watchOS 2 beta 1 is extremely unstable!

Wrapping Up

Apple provides a very simple API for providing haptic feedback to a user through the excellent Taptic Engine. Staying consistent with the intended meanings of the different types will allow a user to learn and understand what you are trying to convey without having to relearn anything while using your application.

How have you implemented Haptic feedback in your Apple Watch apps?

WKInterfacePicker in WatchKit 2.0 - Using The Digital Crown

Apple has provided a new WKInterfaceObject called WKInterfacePicker. It allows you to select an item from a list, similar to the UIPickerView you're already familiar with in iOS 8. You can use it on a list of text, images, and the items are selected by using the Digital Crown.

Picker Styles

There are three main styles you can choose from: List, Stack and Sequence.

List Style Picker

Stack Style Picker

Sequence Style Picker (Images from RadialChartImageGenerator)

The List style is very similar the the UIPickerView in iOS, where you use the crown to select a sequential list of items. The items can be images and text, just text or just images.

The Stack Style animates the items like a stack of cards, providing an attractive way to select an item.

The Sequence Style replaces each image, allowing you to quickly flip between your choices, and also can be used to animate progress bars.

Focus Styles

For each style, you can indicate a focus style, which indicates how you want watchOS to display which picker is in focus. If there is only one picker on the screen, you may want to use None. If you have multiple pickers, you need to indicate which control is in focus and will be affected by the Digital Crown. For example, when customizing the clock face, Outline focus styles are used to indicate which complication is in focus to be adjusted by the Digital Crown.

Each picker item can be annotated by a caption, which can be used to indicate the group or secondary information about the item that will be displayed while picking. The caption can be useful if you are picking images, for example.

Focus Style: None

Focus Style: Outline

Focus Style: Outline With Caption

Coding

Open the Storyboard for your WatchKit App, and drag a Picker into your InterfaceController.

Choose the Style and Focus Style. The Indicator allows you to toggle whether the scroll guide appears beside the Digital Crown. This can be useful for styles like Stack, where it may not be clear to the user where in the list they have scrolled to.

Connect your picker to your interface controller twice, one for the outlet and one for the action.

class InterfaceController: WKInterfaceController {
    @IBOutlet var itemPicker: WKInterfacePicker!

    @IBAction func pickerSelectedItemChanged(value: Int) {
    }
}

We're going to use the IBOutlet to set up the picker with initial values, and the IBAction to react to changes in the picker.

Here's the code for a picker populated with some text:

class ListPickerInterfaceController: WKInterfaceController {
    @IBOutlet var itemPicker: WKInterfacePicker!

    var foodList: [(String, String)] = [
        ("Broccoli", "Gross"),
        ("Brussel Sprouts", "Gross"),
        ("Soup", "Delicious"),
        ("Steak", "Delicious"),
        ("Ramen", "Delicious"),
        ("Pizza", "Delicious") ]

    override func willActivate() {
        super.willActivate()

        let pickerItems: [WKPickerItem] = foodList.map {
            let pickerItem = WKPickerItem()
            pickerItem.title = $0.0
            pickerItem.caption = $0.1
            return pickerItem
        }
        itemPicker.setItems(pickerItems)
    }

    @IBAction func pickerSelectedItemChanged(value: Int) {
        NSLog("List Picker: \(foodList[value].0) selected")
    }
}

Modifying this to support images like in the Stack picker is very simple. Just use the new WKImage and pass those in. If you wanted to create a picker with images frame1.png to frame5.png:

class StackPickerInterfaceController : WKInterfaceController {
    @IBOutlet var itemPicker: WKInterfacePicker!

    var items: [String]! = nil
    
    override func willActivate() {
        super.willActivate()

        items = (1...5).map { "frame\($0).png" }
        
        let pickerItems: [WKPickerItem] = items.map {
            let pickerItem = WKPickerItem()
            pickerItem.contentImage = WKImage(imageName: $0)
            return pickerItem
        }
        itemPicker.setItems(pickerItems)
        itemPicker.focusForCrownInput()
    }

    @IBAction func pickerSelectedItemChanged(value: Int) {
        NSLog("Stack Picker: \(items[value]) selected.")
    }
}

Finally, you'll find that a Sequence picker is set up exactly like the Stack picker:

class SequencePickerInterfaceController : WKInterfaceController {
    @IBOutlet var itemPicker: WKInterfacePicker!

    override func willActivate() {
        super.willActivate()

        let pickerItems: [WKPickerItem] = (0...100).map {
            let pickerItem = WKPickerItem()
            pickerItem.contentImage = WKImage(imageName: "picker\($0).png")
            return pickerItem
        }
        itemPicker.setItems(pickerItems)
    }
    
    @IBAction func pickerSelectedItemChanged(value: Int) {
        NSLog("Sequence Picker: \(value) selected.")
    }
}

Wrapping Up

All of the sample code for this project is available in the Sneaky Crab GitHub. If you're having trouble, make sure to download it and try out the sample code.

WKInterfacePicker provides a simple way to do very attractive and easy to use picking using the Digital Crown in watchOS 2.

What cool interactions have you designed for your watch apps?

Writing a WatchKit Complication in watchOS 2

One of the exciting new additions to the WatchKit Framework in watchOS 2 is the ability to add custom complications to the clock faces provided by Apple. We've written a quick guide on how to add custom Complications to your watch app.

Implement CLKComplicationDataSource

All of the magic happens in CLKComplicationDataSource. Create a new class on your WatchKit Extension target that implements this delegate. Since every delegate method is required, we can start by adding the skeleton of every method in the delegate.

import ClockKit

class Cowmplication: NSObject, CLKComplicationDataSource {
    
    func getNextRequestedUpdateDateWithHandler(handler: (NSDate?) -> Void) {
        handler(nil)      
    }

    func getPlaceholderTemplateForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTemplate?) -> Void) {
        handler(nil)
    }
    
    func getPrivacyBehaviorForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationPrivacyBehavior) -> Void) {
        handler(CLKComplicationPrivacyBehavior.ShowOnLockScreen)
    }
    
    func getCurrentTimelineEntryForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTimelineEntry?) -> Void) {
        handler(nil)
    }
    
    func getTimelineEntriesForComplication(complication: CLKComplication, beforeDate date: NSDate, limit: Int, withHandler handler: ([CLKComplicationTimelineEntry]?) -> Void) {
        handler(nil)
    }
  
    func getTimelineEntriesForComplication(complication: CLKComplication, afterDate date: NSDate, limit: Int, withHandler handler: ([CLKComplicationTimelineEntry]?) -> Void) {
        handler([])
    }

    func getSupportedTimeTravelDirectionsForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTimeTravelDirections) -> Void) {
        handler([CLKComplicationTimeTravelDirections.None])        
    }
    
    func getTimelineStartDateForComplication(complication: CLKComplication, withHandler handler: (NSDate?) -> Void) {
        handler(NSDate())
    }
    
    func getTimelineEndDateForComplication(complication: CLKComplication, withHandler handler: (NSDate?) -> Void) {
        handler(NSDate())
    }
}

You never need to create an instance of this class, and Apple will handle instantiating it using the default constructor.

Understanding Complication Families

There are 5 families of complications that we need to become familiar with in the CLKComplicationFamily enum. From left to right, here are images of ModularSmall, ModularLarge, UtilitarianSmall, UtilitarianLarge, CircularSmall.

From within these families, to populate data, you implement different complication templates related to each family. For example, CLKComplicationFamily.CircularSmall can use the following templates:

• CLKComplicationTemplateCircularSmallRingText
• CLKComplicationTemplateCircularSmallRingImage
• CLKComplicationTemplateCircularSmallStackText
• CLKComplicationTemplateCircularSmallStackImage

There are many templates available. Take a look at the list of subclasses to CLKComplicationTemplate in the ClockKit Framework Reference to see all of the options. Clicking in on a template you can see Apple's visual diagram of how the information in each template is presented.

Configure Info.plist

Go to your targets and select your WatchKit Extension target. Under the General tab, set the Data Source Class to the class delegate we created above prefixed with $(PRODUCT_MODULE_NAME). For example, since our example class was Cowmplication, we put $(PRODUCT_MODULE_NAME).Cowmplication for Data Source Class.

Next, check off which complication families you want to support. Most likely you'd want to support all families, but we're just going to implement CircularSmall for this example.

Set Privacy Behavior

You can choose to show or hide your complication data if the watch is locked, especially if you are displaying more private or sensitive information by passing either CLKComplicationPrivacyBehavior.ShowOnLockScreen or CLKComplicationPrivacyBehavior.HideOnLockScreen to the handler of getPrivacyBehaviorForComplication().

    func getPrivacyBehaviorForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationPrivacyBehavior) -> Void) {
        handler(CLKComplicationPrivacyBehavior.ShowOnLockScreen)
    }

Set Refresh Frequency

Implement getNextRequestedUpdateDateWithHandler() delegate method to tell the watch how often to refresh the complication data. Apple recommends choosing hourly or even an entire day, and providing as much information as possible in a single update cycle with your complication. This will avoid unnecessary battery life drains.

The API gives you a handler you need to call, passing in the date of the next update.

    func getNextRequestedUpdateDateWithHandler(handler: (NSDate?) -> Void) {
        // Update hourly
        handler(NSDate(timeIntervalSinceNow: 60*60))
    }

Implement Placeholder Templates

If data is not populated, especially when customizing the clock face, the OS will show a placeholder for your complication.

You set this up with the getPlaceholderTemplateForComplication() delegate method. It's important to know that this method is called only once, during the installation of your app and the placeholder is cached, so you won't be able to customize this later on.

    func getPlaceholderTemplateForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTemplate?) -> Void) {
        var template: CLKComplicationTemplate? = nil
        switch complication.family {
        case .ModularSmall:
            template = nil
        case .ModularLarge:
            template = nil
        case .UtilitarianSmall:
            template = nil
        case .UtilitarianLarge:
            template = nil
        case .CircularSmall:
            let modularTemplate = CLKComplicationTemplateCircularSmallRingText()
            modularTemplate.textProvider = CLKSimpleTextProvider(text: "--")
            modularTemplate.fillFraction = 0.7
            modularTemplate.ringStyle = CLKComplicationRingStyle.Closed
            template = modularTemplate
        }
        handler(template)
    }

In this example code, we've only implemented the delegate method for .CircularSmall, but in your apps, you'd likely want to configure the look for most or all of the complication types.

For the placeholder, you are not supposed to populate with example data, which is why we put "--" for the text, following what Apple's stock complications do when they put their own placeholders.

Populate Your Complication With Real Data

Next, we'll actually implement the delegate method that will provide real data for the complication. Again, while in the code snippet we only implement .CircularSmall, you would build multiple templates for all of the different complication families you support.

    func getCurrentTimelineEntryForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTimelineEntry?) -> Void) {

        if complication.family == .CircularSmall {
            let template = CLKComplicationTemplateCircularSmallRingText()
            template.textProvider = CLKSimpleTextProvider(text: "\(getCurrentHealth())")
            template.fillFraction = Float(getCurrentHealth()) / 10.0
            template.ringStyle = CLKComplicationRingStyle.Closed

            let timelineEntry = CLKComplicationTimelineEntry(date: NSDate(), complicationTemplate: template)
            handler(timelineEntry)
        } else {
            handler(nil)
        }
    }

This introduces the concept of a CLKComplicationTimelineEntry, which is a container that pairs a date with a complication template. getCurrentTimelineEntryForComplication is used to populate the current complication data, which is why we use NSDate() to indicate the current date and time.

Refreshing The Complication From Your App

It's a very common scenario that while the user is using your app, you'll want to update your complication as you know the data is stale or incorrect. You can use the CLKComplicationServer singleton to trigger updates to your complications.

        let complicationServer = CLKComplicationServer.sharedInstance()
        for complication in complicationServer.activeComplications {
            complicationServer.reloadTimelineForComplication(complication)
        }

Apple has indicated that reloadTimelineForComplication() is rate limited to preserve battery life. If a complication exceeds a daily limit, it will ignore calls to refresh for the remainder of that day.

Build, Run & Test

The completed Complication.

If you didn't make any typos, you should be able to now test & run this on the simulator or on a device. If you are having trouble finding it, make sure that you are looking for it on the right clock face, since not all clock faces support all families of complications.

Time Travel

Improving the code to implement Time Travel is relatively straightforward. First, update getSupportedTimeTravelDirectionsForComplication() to indicate if your complication supports values into the future or the past. For example, a stocks complication would only make sense to show values in the past, while a weather complication could show values in the past and the future.

    func getSupportedTimeTravelDirectionsForComplication(complication: CLKComplication, withHandler handler: (CLKComplicationTimeTravelDirections) -> Void) {
        handler([.Backward, .Forward])
    }

Next, implement getTimelineEntriesForComplication(complication:beforeDate:limit:withHandler:) and getTimelineEntriesForComplication(complication:afterDate:limit:withHandler:) which is similar to getCurrentTimelineEntryForComplication() except that you pass in an array of CLKComplicationTimelineEntry objects. Don't return more objects than limit, and make sure your dates are in sequential order and all occur before or after the passed in dates.

Finally, implement getTimelineStartDateForComplication() and getTimelineEndDateForComplication() to indicate the ranges of time travel you support.

Wrapping Up

You can check out the completed project code on our Sneaky Crab GitHub so you can quickly get going.

Apple has provided a very simple and powerful API to convey simple, glance-able information right on the clock face for app developers.

Tell us about the cool complications that you come up with in the comment section below!

Update 6/22/15: watchOS 2 beta 2 bugs

If you're having trouble with Complications when using beta 2, be aware of the known issues and workarounds from the watchOS 2 Release Notes from Apple.

Known Issues

• Complications are disabled across launches of Simulator.
  Workaround: After enabling a complication in the Watch Simulator you need to lock the watch sim, using Sim Menu > Hardware > Lock (or Command-L), to have the complication still be enabled after quitting Simulator and relaunching.

• Location request dialog text is jumbled in Simulator.

• CLKImageProvider objects do not currently honor the foregroundImage property.
• The CLKComplicationRingStyle property is currently not honored on any CLKComplicationTemplate.
• The CLKRelativeDateStyleOffset enumeration of CLKRelativeDateStyle is not honored for use in CLKRelativeDateTextProvider: It appears as CLKRelativeDateStyleNatural.
• The CLKComplicationPrivacyBehavior on CLKComplicationDataSource is not currently honored.