Protocol

CLKComplicationDataSource

A protocol that defines the methods for communicating with the ClockKit framework.

Overview

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.plist file using the CLKComplicationsPrincipalClass key.)

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:

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.

With one exception, ClockKit does not automatically ask for new timeline entries when the preceding events occur. Instead, you need to call the extendTimeline(for:) or reloadTimeline(for:) methods of the CLKComplicationServer 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 PKPushTypeComplication 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 transferCurrentComplicationUserInfo(_:) to send updates 50 times a day. You can check the remaining number of updates by checking the session’s remainingComplicationUserInfoTransfers property. You can also schedule up to four background app refresh tasks an hour.

Placeholder Templates

During customization of the clock face, ClockKit displays the localizable placeholder template returned by the getLocalizableSampleTemplate(for:withHandler:) 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.

Topics

Getting the Timeline Information

func getSupportedTimeTravelDirections(for: CLKComplication, withHandler: (CLKComplicationTimeTravelDirections) -> Void)

Called to retrieve the time travel directions supported by your complication.

Required.

func getTimelineStartDate(for: CLKComplication, withHandler: (Date?) -> Void)

Called to retrieve the earliest date for which your complication is prepared to supply data.

func getTimelineEndDate(for: CLKComplication, withHandler: (Date?) -> Void)

Called to retrieve the latest date for which your complication is prepared to supply data.

func getNextRequestedUpdateDate(handler: (Date?) -> Void)

Called to get the next time at which to update your complication.

Deprecated

Responding to Scheduled Updates

func requestedUpdateDidBegin()

Called when a requested update begins so that you have an opportunity to extend or reload your timeline.

Deprecated
func requestedUpdateBudgetExhausted()

Called when a scheduled update begins but your complication’s time budget is exhausted.

Deprecated

Providing Templates

func getPlaceholderTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)

Called to get a static template to display in the selection screen for your complication.

Deprecated
func getLocalizableSampleTemplate(for: CLKComplication, withHandler: (CLKComplicationTemplate?) -> Void)

Called to get a localizable template that shows sample data for the specified complication.

Determining the Privacy Behavior

Constants

struct CLKComplicationTimeTravelDirections

Constants indicating the supported time travel directions, if any.

enum CLKComplicationPrivacyBehavior

Constants indicating the complication behavior when the Apple Watch is locked.

Launch Options

Constants indicating launch options for the extension.

enum CLKComplicationTimelineAnimationBehavior

Constants indicating the animation behavior during Time Travel.

Relationships

Inherits From

See Also

First Steps

class CLKComplicationTemplate

An abstract class that defines the base behavior for all templates.