A protocol that defines the methods for communicating with the ClockKit framework.
- watchOS 2.0+
Apps that support a complication must define a class that supports this protocol and register it with the system. Your data source object provides the timeline entries displayed by your complication and provides information about the features that your complication supports.
You do not instantiate your data source class explicitly. After defining your class, specify the class name in the General tab of the project settings for your WatchKit extension. When the system needs data, it instantiates your class and initializes it by calling its
init method. Once initialized, it calls the corresponding protocol methods to gather any needed data. (You can also specify your class name in your app’s
Info file using the
Your data source class is responsible for providing timeline entries and data for all of the complication families that you support. When the user installs your complication on the clock face, ClockKit creates an appropriate
CLKComplication object. That complication object is often passed to your data source so that you know how to format your timeline entries. Use the General tab of your WatchKit extension’s project settings to specify the families you support.
Your complication data source class must implement the following methods of this protocol:
get(watchOS 2 only)
Placeholder Template(for: with Handler:)
get(watchOS 3 only)
Localizable Sample Template(for: with Handler:)
You may implement other methods as needed to support the data in your complication. ClockKit calls the methods of your data source on the main thread of your WatchKit extension.
The Life Cycle of a Complication
ClockKit manages the life cycle of your complication, calling the methods of your data source object at appropriate times to fetch your complication data. Complications are given only a limited amount of execution time each day to preserve battery life. Because their time is limited, ClockKit usually updates complications only when necessary or when asked to do so.
When your complication is first installed on the clock face, ClockKit asks for your complication’s initial set of timeline entries. After that, ClockKit interacts with your complication only when directed to do so. The following events are the times when you would ask ClockKit to update your complication’s data.
When the time specified by your data source’s
getmethod elapses; see
Next Requested Update Date(handler:)
get(watchOS 2 only).
Localizable Sample Template(for: with Handler:)
When your iOS app sends updated complication data using the
transfermethod of a
Current Complication User Info(_:)
When a remote notification of type
When you use a background app refresh task to update your app’s data. For more information see
Refresh Background Task
With one exception, ClockKit does not automatically ask for new timeline entries when the preceding events occur. Instead, you need to call the
reload methods of the
CLKComplication class explicitly to let ClockKit know that it should ask for new data. The only time you do not need to call those methods are when calling one of those methods is what already caused your complication to wake.
The code you execute when responding to complication-related events counts against your complication’s daily time allotment. The implementations of all of your data source methods should return the appropriate data as quickly as possible and not perform any lengthy tasks. Even handling push notifications of type
PKPush in your iOS app counts against your complication’s time budget, so be careful about how you use your time.
In watchOS 3, if the complication is in an active watch face, the iOS app can call
transfer to send updates 50 times a day. You can check the remaining number of updates by checking the session’s
remaining property. You can also schedule up to four background app refresh tasks an hour.
During customization of the clock face, ClockKit displays the localizable placeholder template returned by the
get method of your data source. You must provide placeholder templates for each family of complications you support. Place data in your placeholder templates that typifies the kind of data your complication provides but that is not real data.
ClockKit asks for placeholder templates only once after your app is installed on Apple Watch. It caches the templates you provide and does not ask for them again until your app is reinstalled or updated.
In watchOS 3 and later, users can configure multiple watch faces in the gallery area of the Apple Watch app on iPhone. To add your complication to the gallery, you must create a complication bundle that gives the user a preview of your complication. The complication bundle is stored in your iOS app bundle and used by the Apple Watch app to populate the gallery area.
For instructions on creating the complication bundle, see Adding Complications to the Gallery.