What watch?

Edit: The title of this post has been changed to the original reference of a scene in the movie Casablanca. (What a great movie.)

A small part of the watch world, to be more precise a small part of Apple Watch owners, is currently in a state of open tumult. It started with a blog post from Overcast developer and watch connoisseur Marco Arment and sparked further with an Xcode project from Steve Troughton-Smith using SpriteKit to have an Apple Watch app that mimics a self-designed watch face.

Soon after he published his project on GitHub lots of noobs – like me – saw their chance to get the watch face of their dream onto their Apple Watches. Or the watch face of an unreachable luxury item. Or something illegible else.

Unfortunately there are some hurdles to overcome for us noobs and this incomplete “guide” might help the many who intend to explore the world of watchOS development and Apple Watch faces in general. Please be aware that I totally don’t know what I am and was doing. There might be other or better ways. And of course you are completely liable for any damage and copyright infringements you are doing. So let’s get started.


iOS, watchOS and other Apple OSses development seems to be totally dependant on the versions of operating systems you are running. So your results may vary if you run something else than me. Currently I am running:

  • macOS Mojave 10.14 on my MacBook
  • iOS 12.1 beta 4 on my iPhone X
  • watchOS 5.0.1 on my Apple Watch Series 4

Development target OSses can be changed – but you need to figure this one out by yourself.

Get Xcode

Xcode is available for free on the Mac App Store. Since I am running a beta on my iPhone X I couldn’t build anything for it. watchOS apps need to have a corresponding iOS app. So I needed to install an Xcode beta from Apple’s download page for developers (you need a developer account to see this page – more on that below).

Xcode is a huge download, so plan some time or high bandwidth.

Become an Apple Developer

This used to cost some yearly fees. Luckily Apple can afford to make this free. Head over to https://developer.apple.com/programs/enroll/ to become an Apple Developer. Please be aware that you need an Apple ID in this process. But since nothing works on Apple’s platform without an Apple ID nowadays this shouldn’t be a show stopper.

Add your developer account to Xcode

In the Xcode settings select the “Accounts” tab and add your Apple developer credentials.

Clone Steve’s repository to your Mac

Click on the green button of Steve’s SpriteKitWatchFace GitHub page and copy the URL.

Back in Xcode go to the “Source Control” menu and select “Clone…”

Paste the copied URL into the field “Enter repository URL” and click the “Clone” button.

Save the repository in a memorable place on your hard drive.

Make the project yours

After the cloning Xcode tries to sign the project with Steve’s developer credentials which you obviously don’t have. So you need to change the developer to you in four different places.

To find these places search for “highcaffein” by clicking on the search icon on the left side and entering this search phrase. On each of the lower four search results look for “Developer Team” and change it to your developer account by clicking on the numbers-and-letter code which original stands there. I changed mine to “Yves Luther”. Don’t forget to do this for all of the lower four search results.

Go for your first build

If I remember correctly you should be able to build the macOS test app now. Do this by clicking on the button after the play (build) and stop (stop running) buttons on the upper left.

Select “DesktopShim” and “My Mac” there. Depending on the speed of your Mac this may take some time. Don’t be afraid of some warnings. But be afraid of errors, because their solving involves lots of DuckDuckGo-ing for a noob like me.

If everything goes according to plan you are greeted by the DesktopShim app. Here you need to know some of the key strokes Steve mentioned in his commit notes. E.g. these:

Pretty nice, isn’t it?

Start customizing

Now things get dangerous. You can skip this step if you just want to rock the plenty default options Steve provides – they are in the high thousands.

Though you can later change the themes on your Apple Watch by spinning the crown other customizations like the numbers, ticks, etc. needs to be changed in code. Therefore click on the folder icon on the top left and select the file “FaceScene.m”.

Here are some of the options defined. What options you may ask? Well, the available options are found in the file “FaceScene.h”.

If you can’t imagine what each option means you can either try them all or remember them from “DesktopShim” app earlier.

If you like to change the colors of an existing theme you can find them in the “FaceScene.m” file:

Alternatively you can copy and paste an existing theme. Don’t forget to rename it and add it to the available themes in the file “FaceScene.m”:

If you want to go to the noob’s limit and glue the rotating color region to the hour hand (instead of the default minutes hand) you can change this here in the “FaceScene.m” file:

Please remember that the option “self.colorRegionStyle” needs to be set to “ColorRegionStyleDynamicDuo” for this to happen.

Build for the simulator

Beside the possibility to test your customizations in the “DesktopShim” app you could also use Xcode’s simulator app. Do you smell how you are getting closer to the metal? To do so, select “SpriteKitWatchFace WatchKit App” and “iPhone XS Max + Apple Watch Series 4” from the button after the play (build) and stop (stop running) buttons.

I am unsure how this combination of iPhone and Apple Watch got there. So it may vary in your case or it may be dependant on what development devices you have added (more on this later). Maybe you can tweet me what’s going on on your machine.

After hitting the play button, a new build is initiated and after a looong time the simulator fires up showing the Apple Watch and the iPhone. Both apps get automatically installed. On the Apple Watch click on the crown to see the app launcher:

On the iPhone “swipe” with your mouse to the second screen:

There they are.

On the Apple Watch click in the “Duotone” icon and the app launches:

Now you are greeted by your customized SpriteKit Watch Face app:

Use the (virtual or real) scroll wheel on your mouse to change the theme until you reach your customized one.

Add your development devices

After some deep thinking I’ve remembered what I did to add my iPhone X and my Apple Watch Series 4 to the development devices of my Apple Developer account.

Head over to this URL: https://developer.apple.com/account/ios/device/ you

a) need to have an Apple Developer account and
b) be logged in

to see this page. Click on the plus button in the upper right and you see this screen:

Give your iPhone a memorable name, maybe keep similar to its generation if you plan to have a plethora of devices and become a full-time indie developer in the future.

Regarding your iPhone’s UDID fire-up iTunes with your iPhone connected via USB and click on the “ECID” which then change to the “UDID.”

Right click on it and select “copy” to copy it and paste it in the corresponding field of the above mentioned web page.

Now onto the Apple Watch. To retrieve the Apple Watch UDID go to Xcode (beta) and there chose “Devices and Simulators” from the “Window” menu. Your iPhone still needs to be connected via USB. Under the “Paired Watches” section you find your paired Apple Watch. Double-click on the number below “Identifier”, select all and then copy your Apple Watch UDID. Head over to the developer devices web page and add your Apple Watch as a second device.

Done and done.

Now for a theory: You may add your iPhone directly in Xcode (beta). It is late now and my wife wants to go to bed. So please try by yourself if instead of adding your devices on Apple’s developer devices page you can go directly to “Devices and Simulators” from the “Window” menu, click on the plus button on the lower left corner, select your iPhone and proceed by clicking on the “Next” button in the lower right. What comes afterwards? I don’t know but you get the idea.

Build for the iPhone and Apple Watch

By now you probably know what to do. Connect your iPhone via USB (and optional USB-C dongles) to your Mac and select “SpriteKitWatchFace WatchKit App” and “iPhone X + Yves’s (sic) Apple Watch” from the button after the play (build) and stop (stop running) buttons. Your combination may vary and should be selected from the “Device” section.

Hit the play button and a new build is compiled and transferred to your iPhone. Now the music continues playing there:

I don’t know if this is necessary but you may just launch the “Duotone” app for your enjoyment.

Afterwards head over to the stock “Watch” app, go to the “My Watch” screen and scroll down to the “Available Apps” section. There, click on the “Install” button of the “SpriteKitWatchFace WatchKit App”.

Soon the “SpriteKitWatchFace WatchKit App” may be found under the “Installed on Apple Watch” section.

Nothing is to do there so head over to your Apple Watch.

You have reached the end

On your Apple Watch you should go into your settings and chose under “General” > “Wake Screen” > “On Screen Raise Show Last App” > “Always”. This is to ensure, that once you have started your newly created watch face app it stays visible on each arm raise. (Occasionally, especially if you are using other apps on your Apple Watch, the newly created watch face app will descend in your app stack so you need to elevate it again by doing the following again – each time this happens.)

Now press your crown to see all installed apps and tap on “SpriteKitWatchFace WatchKit App” and a few seconds later your work of art shines in all its glory on your Apple Watch. Again spin the crown until your own watch face is visible. Of course you could later delete all other watch faces, if you don’t need them any more.

Quo vadis from here

Steve is still refining his work. E.g. he added the possibility to show the date in different styles and in four different spots. I wish this spot is selected automatically depending on the positions of the hands. I should file an issue on GitHub for that.

Complications are still a problem: the existing ones can’t be added. I don’t know if this is just for now or maybe possible later. As a workaround other developers are implementing them directly in their watch faces. Of course this needs some serious coding skills.

Joseph Shenton, another developer genius, is building a companion app, where all the customizations can be done in an iOS app on your iPhone. Steve already signalled that he will incorporate the companion app in the coming days in his repository.

Especially the companion app and the collaboration between Steve, Joseph and David Smith is mind blowing. I like the Internet for this a lot.

I hope their and our activities are putting some serious pressure on Apple to officially support the development of watch faces by 3rd parties. Copyright issues beside, which could easily be sorted out through the App Store review process, there are tremendous opportunities ahead to make the Apple Watch personal again. I can’t wait for this to happen.

Update – Steve Troughton-Smith seemed to be bored a little. So he re-wrote his watch face project in Swift as a Playground Book – for your enjoyment in Apple’s Playground app.