A protocol that communicates with ClockKit, providing information about your complication.


protocol CLKComplicationDataSource


Apps that support a complication must define a class that supports the CLKComplicationDataSource protocol and register it with the system. Your data source is responsible for providing timeline entries and data for all of the complication families that you support. You do this by implementing the protocol methods, returning the timeline entries displayed by your complication and information about the features that your complication supports.

You don’t 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, ClockKit instantiates your data source and initializes it by calling its init method. Once initialized, ClockKit 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).

When the user installs your complication on the clock face, ClockKit creates an appropriate CLKComplication object for the selected complication family. That complication object is 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 CLKComplicationDataSource methods:

You may implement other methods as needed to support the data in your complication. ClockKit calls the methods of your data source on your watchOS app’s main thread.

For more information, see Providing Data for Your Complication.


Getting the Timeline Information

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

Determines whether your complication can provide timeline entries for the future or the past.


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

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

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

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

Determining Always On Behavior

Providing Templates

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

Gets a localizable template that shows sample data for the specified complication.

Determining the Privacy Behavior

Launch Options

let CLKLaunchedTimelineEntryDateKey: String

A key indicating the date with which the complication was launched.

Information Property Keys

property list key CLKComplicationPrincipalClass

The name of the class that implements the complication data source protocol.

Name: ClockKit Complication - Principal Class

Deprecated Methods

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

Gets the next time at which to update your complication.

func requestedUpdateDidBegin()

Indicates that a requested update has begun so that you’ve an opportunity to extend or reload your timeline.

func requestedUpdateBudgetExhausted()

Indicates that your complication’s time budget is exhausted.

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

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



Inherits From

See Also


Adding a Complication to Your watchOS App

Build a better watchOS experience using complications.

Creating and Updating Complications

Build complications that display current information from your app.

Displaying Essential Information on a Watch Face

Display essential information on a watch face by implementing complications in a watch app.