watchOS

ClockKit Tutorial: Add complication to an already existing watch project (ClockKit #1)

I’m happy to announce that I’ll be starting a new series of posts looking into different topics in ClockKit. For those of you who are unfamiliar, ClockKit is a new framework provided by Apple during WWDC ’15 that allows third-party apps to create their own custom complications for their watch apps.

Until about a week ago, I was surprised at the lack of third-party complications in the app store. However, after looking into ClockKit, I have hypothesized a number of reasons why this is happening, including the topic I’m about to cover today. I’ll be going over the rest of these ideas over the duration of this ClockKit series.

Now, onto the matter at hand. The Creating Complications with ClockKit video from WWDC ’15 is a great introduction to, well, creating complications. What Apple has failed to mention though is that while adding a complication to a brand new watch project is trivial, unfortunately, adding a complication to an already existing project is a very manual and tedious process. Hopefully, the developers of Xcode will add a way to insert a complication into your existing project more easily, but until then, here’s how to do it.

Complication

Note: All of the below assumes you’re already on a watchOS 2 app. If you’re not, make sure to upgrade the existing project before you do the rest.

WatchKit Extension Files

In your already existing watch project, go to File -> New -> Project. Under watchOS, create a new WatchKit App and click Next. Enter in any name for this app – you’ll eventually delete it once you extract the portions that you need. Make sure to click the checkmark next to Include Complication. Click Finish.

Complication Setup

Once your new watch app is created, you should see two new folders at the bottom of your file explorer with the name that you just gave them. Open the temporary Extension folder and highlight the ComplicationController files (both .h and .m if you’re using Obj-C or just the .swift file for Swift).

If your watch project is old enough and it doesn’t have an ExtensionDelegate, I would highlight that one too to add to your WatchKit extension. This basically acts just like the AppDelegate file for your iOS app.

Drag the file(s) into your existing WatchKit extension.

New complication files

Once you’ve done this, you’ll also have to go through each file and change it’s target membership to the existing extension. Make sure to uncheck the temp extension too. In Obj-C, you’ll only have to do this for the .m files.

Target membership

Info.Plist

Next, we need to add in three things from the temp info.plist file. If you open it, you’ll see some keys:  CLKComplicationPrincipalClass, CLKComplicationSupportedFamilies and WKExtensionDelegateClassName. You can either highlight each one and copy and paste it from your temp plist to your existing extension plist, or you can open your existing extension plist and just paste in this XML before the </dict> at the end of the file:

<key>CLKComplicationPrincipalClass</key>
<string>ComplicationController</string>
<key>CLKComplicationSupportedFamilies</key>
<array>
<string>CLKComplicationFamilyModularSmall</string>
<string>CLKComplicationFamilyModularLarge</string>
<string>CLKComplicationFamilyUtilitarianSmall</string>
<string>CLKComplicationFamilyUtilitarianLarge</string>
<string>CLKComplicationFamilyCircularSmall</string>
</array>
<key>WKExtensionDelegateClassName</key>
<string>ExtensionDelegate</string>

Configure the Complication Scheme

Next, you’ll have to do is set up the complication scheme so you can launch the watch simulator to the home screen with your complication.

Click on your scheme list and select the temp complication scheme. Once it’s selected, click it again and go to Edit Scheme.Edit Scheme

Here, under the Run -> Info tab, you’ll need to change your Executable from the temp app to your existing watch app.Executable

To rename the scheme, you’ll want to click on Manage Schemes at the bottom of this window. Slow-double-click on the scheme you want to rename, and you can edit the text from there.

Manage Schemes

Project Configuration

The last thing you’ll have to do is to configure your complication and clean up some of the project files. To clean up all the unnecessary files,  you can go ahead and delete the temp app and temp extension folders, along with the temp app scheme.

You’ll also need to modify some project settings. Click on your overall project in the Project navigator. Under Targets, you can delete the temp targets that you created. Select the extension target for your existing watch project.

Complication config

You should see something that looks like the screenshot above. Choose ComplicationController for your Data Source class. From here, you can choose which family of complications you want to support. Apple recommends that you support as many as you can so that users will be more likely to use your complication. In this case, just to test it out, I’m just going to check the Utilitarian Large one. Run your complication scheme at this point.

Your watch simulator should launch with the default Utilitarian face (unless you’ve changed it to something else). Deep press (Cmd-Shift-2) to get to the customization screen for your watch face. Shallow press (Cmd-Shift-1) the Customize button, swipe right until to get to the complications configuration, and choose the complication family that you have decided to support. When you scroll through the list, you should see the name of your watch app come up.Scroll complication

Of course, you haven’t done anything yet, so it just reads the name of your watch app, but that’s just the first step. Happy complication making!

Thanks to Gamma-Point for the original stack overflow post that taught me how to import the complication files.

4 thoughts on “ClockKit Tutorial: Add complication to an already existing watch project (ClockKit #1)

  1. OOO more please, this tutorials a great start but an in-depth one on updating complications would be excellent. Apple are so difficult over this and knowing the ins and outs would be great!

  2. dont know if it is an type error or a different approach, File -> New -> Project, I did this File -> New -> Target, and everything else like you did in the example and in worked than without problems, otherwise I had some problems. TNX, great tutorial just like the one with WatchConectivity

Leave a Reply