*********** ERROR -[SPRemoteInterface _interfaceControllerClientIDForControllerID:] clientIdentifier for interfaceControllerID:114D0003 not found

Generally this doesn't seem all too helpful. What is interfaceControllerID:114D0003 anyway?

It turns out this is the ID in a private property called _viewControllerID. There is a little bit of code you can add to your willActivate() to see what the _viewControllerID is for each of your pages.

    override func awakeWithContext(context: AnyObject?) {
        super.awakeWithContext(context)
        if let vcID = self.valueForKey("_viewControllerID") as? NSString {
            println("Page One: \(vcID)")
        }
    }

With a little bit of key-value coding trickery, we can get access to the private variable. Knowing exactly which WKInterfaceController is misbehaving really saves time when you're hunting down to clear out all references to the old controller before blowing it away with the reloadRootControllersWithNames call.

Hope this quick tip helps all of you too.

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.

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?

Picker Styles

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

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.

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?

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

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.

The WatchKit Extension now runs on the Apple Watch

In watchOS 1, the WatchKit extension ran as an extension of your iOS App. In watchOS 2, it runs natively on the Apple Watch. This is great because you get native performance without the slow back-and-forth communication over Bluetooth for every UI interaction.

There is a downside though–current WatchKit extensions enjoy the use of every iOS API, whereas the new watch OS 2 apps have access to a subset of APIs available only to WatchKit. For example, if your extension depended on CloudKit, you can't use it directly on the Watch and will have to contact the parent iOS app if you want to continue using that functionality.

Watch Connectivity is for synchronizing the iPhone and Watch

Now that the watch app runs on the actual watch device, synchronizing data and state between the iPhone and watch is a little trickier. Apple has added Watch Connectivity with the WCSession class to facilitate communication between the two devices.

You bundle watchOS 1 & 2 apps in the same app

Apple will allow you to continue to bundle the old WatchKit extension code for watchOS 1 users in addition to shipping new code for watchOS 2. If you do this, sharing code might be tricky as different APIs are available between the two and it doesn't appear as though embedded frameworks will work on the watch.

WKExtensionDelegate is the AppDelegate for WatchKit

One of the annoying things in watchOS 1 was how difficult it was to track app lifecycle changes. Now you simply implement WKExtensionDelegate similar to how you implement AppDelegate on iOS. There's a simplified lifecycle, with three states: Not Running, Inactive and Active.

You can add Complications for your app to the watch face

If you implement CLKComplicationDataSource from ClockKit, you can set up complication information. You provide a timeline, where you describe the various changes to your complication throughout the day, as well as an interval for when ClockKit should refresh your complication. There is also a high-priority push-notification that you can use meant for updating the Complication in real time.

Check out our guide on Writing a WatchKit Complication.

You can play Video and Audio content on the watch

For embedded video and audio in your UI, use WKInterfaceMovie. To present this in a new controller, use presentMediaPlayerControllerWithURL:options:completion:. If you want to play extended content that continues playing even when your app is inactive, use WKAudioFilePlayer and set up the audio value in UIBackgroundModes in your Info.plist.

Audio plays directly on the watch, prioritizing the Bluetooth speaker, but will also use the built-in speaker if a Bluetooth speaker is not available.

You can record audio with the microphone

It seems you can only do it through Apple's stock audio recording controller, calling presentAudioRecordingControllerWithOutputURL:preset:maximumDuration:actionTitle:completion:. There doesn't seem to be a way to record audio and process realtime audio or record audio inline or using a custom controller or UI.

You can use the Taptic Engine to provide haptic feedback

WKInterfaceDevice.playHaptic() will provide haptic feedback. You can pick from one of the choices in the WKHapticType enum. We didn't find a way in the documentation or header files to define custom haptic feedback.

Check out our guide on Writing Haptic feedback on the Taptic Engine.

Digital Crown Access

The WKInterfacePicker handles digital crown access. You can have a List UI, a stack of cards that animate, or an image sequence that responds to the digital crown. We didn't find a way to read raw delta values from the crown in the current API, which may be useful for game developers.

Check out our guide on coding your own WKInterfacePicker: Using the Digital Crown.

Access to Sensors

Opening up Xcode 7, we were able to import CoreMotion and instantiate a CMMotionManager in a test WatchKit Extension project. This appears to work exactly like in iOS. We assume that heart rate and step data are also available through the HealthKit framework.

HealthKit, HomeKit, PassKit, CoreLocation, CoreGraphics

In Xcode 7, we were able to import and instantiate objects from all of these libraries from within our WatchKit extension project, so we assume that these work just as they do from iOS. CoreAnimation did not appear to be available.

Xcode Simulator

The Xcode simulator now fully supports the watch. This means that you can test glances, notifications, watch complications and so on. You can also debug and run the watch and device simulators simultaneously which was not possible in watchOS 1 simulators.

In addition, the Hardware menu has added "Simulate Touch Pressure" with an option for Shallow Press and Deep Press. Scrolling your mouse-wheel simulates digital crown movement, and pressing ⌘⇧H simulates pressing the crown in.

To be continued...

As WWDC unfolds, we'll update the information here with corrections and the latest information as Apple provides it. All in all, watchOS 2 is an extremely exciting improvement for developers, and we can't wait to update Chairman Cow to the new features, and stay tuned as we are determined to bring you world class watchOS 2 apps and games this fall!

Edit: 6/8/15 Added information about recording audio/microphone.

One of the most maddening things is how long it takes to install an app to a real Watch. This was particularly frustrating lately for two reasons:

1. The simulator, while helpful, sometimes has different bugs or behaviors from the Watch itself.
2. Apple has not released an updated version of Xcode with a WatchOS 1.0.1 simulator, so testing new behaviors such as the change to WKInterfaceController didAppear() caching requires testing on a real Watch.

Let's take a journey to find the fastest way to get from building to having a debugger attached to the Watch app and save all of our sanity.

The most expensive part is installation, so we profiled modifying a few variables to see what made the biggest impact for install time of our app. We tested installing the app over Bluetooth and also forced app install over Wi-Fi, and also tried to see if having the Apple Watch App open, on the app detail and not asleep mattered. This was tested on Xcode 6.3.2, iOS 8.2 and WatchOS 1.0.1.

From our admittedly unscientific tests, we can draw two conclusions:

1. Bluetooth installs seem to be significantly faster if the Apple Watch App is in the foreground
2. Wi-Fi was fast in every test.

Due to the consistency of the Wi-Fi approach, I'll focus on that here.

Setup

Make sure that your Apple Watch is set up to use Wi-Fi.

• The Apple Watch can only use 2.4 Ghz Wi-Fi networks, so if your Wi-Fi is 5 Ghz and you can't enable 2.4 Ghz, you're out of luck.
• The phone will automatically share Wi-Fi credentials with your watch.
• You can test if it is working by turning off Bluetooth on your phone, and seeing if you can still use Siri or make a phone call with your watch.

Make sure your Apple Watch is paired with your iPhone, and it's identifier has been added to your Devices section in Certificates, Identifiers & Profiles in developer.apple.com.

Fastest Build -> Install -> Run -> Debug Cycle

1. Turn off Bluetooth on your phone. The fastest way is to swipe up control center and toggle it there. You'll get a dialog nagging you to turn it back on–hit cancel. We do this first to make sure that the system doesn't accidentally start installing the app over Bluetooth. If you turn off Bluetooth after it began installing over Bluetooth, we've found it hard to convince the phone to continue installing over Wi-Fi. It seems to prefer the network type it began the install.
2. Hit stop in Xcode until it greys out. We've had lots of problems with Xcode attached to different old processes that cause problems later on. We recommend ensuring you're in a clean state.
3. Choose the iOS base scheme in Xcode, and your device. If you build and run the WatchKit Extension scheme here, Xcode will time out trying to attach while you're waiting for it to install on the Watch which is more dialogs for you to click on.
4. Click the Xcode play button to begin build and installation to your phone.
5. When the iOS App starts running, multitask back to the Apple Watch App, open the page for your App. While this doesn't seem to speed up Wi-Fi installs, the system seems to notice faster that it needs to install an updated watch app than when you aren't on this screen. Obviously, make sure Show App on Apple Watch is enabled.
6. Your app should install to device in about 1 minute.
7. Turn on Bluetooth. You can't launch or debug your app over Wi-Fi, so this must be done. Again, swiping up control center is the fastest way to toggle Bluetooth.
8. Back in Xcode, press ⌘6 to open the Debug Navigator  
9. Hit stop again, switch to the WatchKit Extension Scheme in Xcode. Now we're going to attach debugging.
10. Hit play in Xcode, when it is ready, you'll see in Debug Navigator show the extension as "Waiting to Attach".
11. Manually open the app on your watch, and you'll see Xcode magically attach to the process.

Phew. That's a lot of steps. But we got pretty fast at it while we were trying to debug issues in our Chairman Cow game with WatchOS 1.0.1, and it's better than waiting 4 minutes per build for the app to install.

This is the best method we found. What are your tips and tricks for efficient Build ➡ Run ➡ Debug on a real watch? Please tell us if you have found a better way!

While this is effective in reducing loading spinners that users will see, it can cause bugs based on some common assumptions that developers might make.

Let's first take a moment to understand deeply the change in the calling pattern.

In WatchOS 1.0, Apple would call willActivate() only just before the page is visible, and didActivate() only just as the page is losing visibility. This pattern could occur if the watch is going to sleep, or transitions between interface controllers.

Here's a trace of a page-based interface with 5 interface controllers.

WatchOS 1.0 Life Cycle

00:50:07.583 page0: init()
00:50:07.585 page0: awakeWithContext()
00:50:07.780 page1: init()
00:50:07.780 page1: awakeWithContext()
00:50:07.994 page2: init()
00:50:07.995 page2: awakeWithContext()
00:50:08.190 page3: init()
00:50:08.190 page3: awakeWithContext()
00:50:08.317 page4: init()
00:50:08.317 page4: awakeWithContext()
00:50:08.514 page0: willActivate()

Swipe to next page (page1)

00:50:16.527 page1: willActivate()
00:50:16.721 page0: didDeactivate()

Swipe to next page (page2)

00:50:22.713 page2: willActivate()
00:50:22.909 page1: didDeactivate()

Pretty straightforward. It will call init() ➡ awakeWithContext() on all pages, activate the first page (page0). On a swipe, it will first activate the next page, then deactivate the old page.

Let's look at a trace from WatchOS 1.0.1.

WatchOS 1.0.1 Life Cycle

23:55:18.750 page0: init()
23:55:18.753 page0: awakeWithContext()
23:55:18.990 page1: init()
23:55:18.991 page1: awakeWithContext()
23:55:19.289 page2: init()
23:55:19.290 page2: awakeWithContext()
23:55:19.748 page3: init()
23:55:19.749 page3: awakeWithContext()
23:55:19.764 page4: init()
23:55:19.765 page4: awakeWithContext()
23:55:19.768 page0: willActivate()
23:55:22.751 page1: willActivate()
23:55:23.291 page1: didDeactivate()

Swipe to next page (page1)

23:55:43.953 page1: willActivate()
23:55:44.040 page0: didDeactivate()
23:55:44.853 page2: willActivate()
23:55:45.633 page2: didDeactivate()

Swipe to next page (page2)

23:56:08.436 page2: willActivate()
23:56:08.552 page1: didDeactivate()
23:56:09.397 page3: willActivate()
23:56:10.115 page3: didDeactivate()

We can see that the init() ➡ awakeWithContext() call pattern is the same, but as soon as page0 is activated, it immediately activates, then deactivates page1.

Common Issues

While Apple's caching works well for populating the contents of the UI, but most issues revolve around doing any non-view configuration work in willActivate(). In particular, detecting visibility state change of the WKInterfaceController.

Here's a few scenarios that are more difficult in WatchOS 1.0.1:

Asynchronous updates kicked off by willActivate(). For example, willActivate() kicks off some network calls to populate data, and when it returns, didDeactivate() has already been called, so the updates will fail.

Knowing which interface controller is visible. For example, your MMWormHole is reporting a change on your iOS app, and you'd like to call a function on only the visible interface controller to refresh UI.

Workarounds/Solutions

Async Updates Solution: Track Visibility Within the WKInterfaceController

If we want to trigger event on first visibility, it is possible to track active state within the controller itself, and save any UI updates for when the controller is truly active.

class MyInterfaceController: WKInterfaceController {
    var isActive: Bool = false
    var pendingContext: AnyObject? = nil
    
    override func willActivate() {
        super.willActivate()

        isActive = true
        if let context: AnyObject = pendingContext {
            updateUI(context)
            pendingContext = nil
        } else {
            beginAsyncCallWithCallback(callback)
        }
    }
    
    override func didDeactivate() {
        super.didDeactivate()
        isActive = false
    }
    
    func callback(context: AnyObject) {
        if isActive {
            updateUI(context)
        } else {
            pendingContext = context
        }
    }
}

Visible Controller Solution 1: Assume that visible is always activated first.

In the calling patterns of 1.0 and 1.0.1, the visible controller always gets willActivate() called first. If we assume that this will always hold true, we can definitively know which controller is visible.

Each time willActivate() is called, track it in an activeControllers dictionary along with the timestamp. Remove it when didDeactivate() gets called. When we want to know which controller is the visible one, return the controller with the smallest timestamp.

class RefreshableInterfaceController: WKInterfaceController {
    override func willActivate() {
        super.willActivate()
        // Do NOT call ControllerTracker.sharedInstance.visibleController() here
        // The previous page will not have called didDeactivate yet. 
        // Make sure to delay that call.
        ControllerTracker.sharedInstance.addActiveController(self)
    }
    
    override func didDeactivate() {
        super.didDeactivate()

        ControllerTracker.sharedInstance.removeActiveController(self)
    }
    
    func refreshUI() {
        // Refresh UI
    }
}

class ControllerTracker: NSObject {
    var activeControllers: [RefreshableInterfaceController : CFAbsoluteTime] = [:]
  
    func addActiveController(controller: RefreshableInterfaceController) {
        activeControllers[controller] = CFAbsoluteTimeGetCurrent()
    }
    
    func removeActiveController(controller: RefreshableInterfaceController) {
        activeControllers.removeValueForKey(controller)
    }
    
    func visibleController() -> RefreshableInterfaceController? {
        var earliestController: RefreshableInterfaceController? = nil
        var earliestTime: CFAbsoluteTime? = nil
        for (controller, timestamp) in activeControllers {
            var foundBetter = false
            if let time = earliestTime {
                if time > timestamp {
                    foundBetter = true
                }
            } else {
                foundBetter = true
            }
            if foundBetter {
                earliestController = controller
                earliestTime = timestamp
            }
        }
        return earliestController
    }
    
    class var sharedInstance: ControllerTracker {
        struct Singleton {
            static let instance = ControllerTracker()
        }
        return Singleton.instance
    }
    
    func resetControllers() {
        activeControllers.removeAll(keepCapacity: false)
        WKInterfaceController.reloadRootControllersWithNames(initialControllers, contexts: contexts)
    }

    func refreshVisibleController() {
        visibleController()?.refreshUI()
    }
}

With this strategy, it's extremely important to clear the activeControllers before you call reloadRootControllersWithNames or you might orphan a controller that you need. See resetControllers() for example.

The flaw with this strategy is in the assumption, that Apple will always create the visible controller first before caching the next one. The API documentation makes no guarantees on call order, so this solution is definitely hacky. It's a "safe hack" though, since logically Apple would likely want to start loading the first visible controller before trying to cache others. There are lots of reasons, including threading races, as to why this assumption could be broken in the future.

Visible Controller Solution 2: Poll until only one controller active.

If we dislike the above hack, another option is to wait until our activeControllers dictionary resolves down to exactly one element. It works the same as the Solution 1 code snippet with just visibleController() and refreshVisibleController() changed.

class ControllerTracker: NSObject {
    func visibleController() -> RefreshableInterfaceController? {
        if activeControllers.count != 1 {
            return nil
        }
        return activeControllers.values[0]
    }
  
    func refreshVisibleController() {
        if let controller = visibleController() {
            controller.refreshUI()
        } else {
            NSTimer.scheduledTimerWithTimeInterval(0.1, target: self, selector: "refreshVisibleController", userInfo: nil, repeats: false)
        }
    }
}

The problem with this strategy is that polling causes additional lags and is generally messy control flow every time you want to take an action on the visible controller. The above solution also requires additional code to be production ready. This code will poll forever if activeControllers is empty. (e.g. the watch went to sleep)

Final Thoughts

There is currently no way to detect if the watch is running WatchOS 1.0 or 1.0.1, so the code needs to be written in such a way that it works on all OS versions. It appears that Apple's intention is that willActivate() and didDeactivate() are intended just for setting up and tearing down views and no additional side effects should be occurring in the watch app. This is great in theory, but unfortunately there are no convenient method to actually know the difference between interface controller setup and the interface controller actually appearing.

The flow is really nice in iOS: init ➡ viewDidLoad ➡ viewWillAppear ➡ viewDidAppear and viewWillDisappear ➡ viewDidDisappear ➡ viewDidUnload ➡ dealloc. On the watch, perhaps this is overkill, and I can see them wanting to reduce communication over Bluetooth by reducing the number of events going over the air.

However the current state of the WatchKit API leads developers to a lot of hacks and workarounds when writing non-trivial code. Even if the watch UI is simple and clean, the underlying logic is sometimes necessarily complex to bring data from other sources cached and ready to go just-in-time.

Let's hope that improvements come in future updates.