watchOS: Complications

Feb 7 2023 Swift 5.6, watchOS 8.5, Xcode 13

Part 1: Introduction to Complications

1. Explore Complications

Episode complete

Play next episode

About this episode
Leave a rating/review
See forum comments
Cinema mode Mark complete Download course materials
Next episode: 2. Create Your First Complication

The materials from this course are based on our book watchOS With SwiftUI by Tutorials. If you’re new to watchOS development, check out the book to get started!

Apple’s documentation on ClockKit shows images of exactly where each type of complication displays on the watch face, as well as examples of each template type.

Hi everyone! I’m Catie. Welcome to this course on complications for watchOS. Complications are my favorite part of watchOS development, so let me give you the pitch.

When you design an iOS app, it’s normal to expect users will engage with your app for 5 to 10 minutes. For some apps, especially on an iPad, that could extend to hours.

But a watch app is different. Most users will only engage with a watch app for a few seconds. To help Apple Watch users make the most of your app, you should always consider adding complications.

I am not a “watch person”, so this term confused me a bit at first. Why would I want to complicate my app?

Traditionally, according to Wikipedia, a watch complication is any feature of a mechanical timepiece beyond the display of hours, minutes and seconds.

By that definition, the Apple Watch is full of complications!

On the Apple Watch, complications have been slightly redefined as elements on a watch face that display small, immediately relevant bits of information. They are one of the most compelling and useful features of the Apple Watch.

They’re right there on the watch face, so checking them is as fast as raising your wrist. They’re sort of the watch equivalent of widgets on iOS, but even faster to access.

So, unless there’s a compelling reason not to include one, every watchOS app should include at least one complication.

Why complications?

Imagine the types of questions you can instantly answer by having a complication available on the watch face:

  • How far away is my next turn?
  • What’s the score?
  • Is it going to rain in the next hour?
  • When will the brownies be done?
  • Did someone feed the cat already today?

Even if your app doesn’t really have data that makes sense to display on a watch face, adding a complication gives your user a way to launch your app with a single touch of the screen.

On top of that, watchOS offers significant benefits to your app when a user also includes your complication on their watch face:

  • watchOS keeps your app in memory and gives it extra update time, making app launches almost instantaneous.
  • Your app can perform additional background refresh tasks.
  • Your complication can receive up to 50 pushes of updated information per day.
  • And, the complication for your app can be featured in the Apple Watch Face Gallery on the phone.

In this course, we’ll dig into the technical details of using the ClockKit framework to implement complications and learn how to keep them up-to-date with current information.

In other words, by providing complications, you’ll uncomplicate your app.

Complication families

So, you’re ready to create a complication! Awesome. Can you just make whatever you want? Create a complication that takes up the whole watch face?

No. That would be designing your own watch face, which, sadly, Apple doesn’t allow. So we’re limited by the fact that our complications have to fit in the watch faces Apple provides. But that is less limiting than you may think.

There are a lot of watch faces, and more come along with each new version of watchOS. Watch faces feature different layouts and support different numbers of complications. They also support different types of complications.

Apple groups the types of complications into families, represented by the CLKComplicationFamily enumeration type.

There are currently 12 different families, each one with a distinct set of templates. Support all of the complication families to provide the best user experience.

Complication templates

[Slide 02]

Within each family, Apple provides multiple templates which describe the layout of the complication. Most of the templates consist of simple text and images, but some do provide partial SwiftUI View support.

Complication Reference

You can find a visual reference for all of the families and templates in the materials for this course.