Adding Complications to the Gallery

Configure watch faces in the gallery area of the Apple Watch app on iPhone.


In watchOS 3 and later, users can configure multiple watch faces in the gallery area of the Apple Watch app on iPhone. To provide a more accurate preview of your complication in the gallery, provide a complication bundle with placeholder data. The complication bundle is stored in your iOS app bundle and used by the Apple Watch app to populate watch faces in the gallery.

You use Xcode and Watch Simulator to build your complication bundle. Watch Simulator captures output from your watchOS app and uses it to create the complication bundle. Follow the steps below to create your complication bundle and add it to your iPhone app.

  1. Implement the getLocalizableSampleTemplate(for:withHandler:) method in the class that adopts the CLKComplicationDataSource protocol. In your implementation, create a template of the appropriate type for the specified complication family and assign placeholder values to its properties.

  2. Launch your app in Watch Simulator and make it frontmost.

  3. In Watch Simulator, choose File > Save Complication Bundle. (Xcode generates a complication bundle and gives it the name that you enter. For example, MyBundleName.ckcomplication.)

  4. Add the generated complication bundle to your iPhone app. (You must add the complication bundle as a resource to your iPhone app, not to your watchOS app. When you add the bundle, select "Create folder references" in the "Choose options for adding these files" Xcode dialog.)

  5. In Xcode, launch your app on iPhone. (When you launch the Apple Watch app and go to the gallery area, you should see an entry for your app.)

When building your templates, you can specify localized placeholder text using a simple text provider:

Listing 1

Creating a simple text provider from localized strings

CLKSimpleTextProvider.localizableTextProvider(withStringsFileTextKey: "AKey")

The keys you use for your simple text provider must appear in a localized strings file named ckcomplication.strings. This strings file should also be in your WatchKit extension bundle.

See Also


class CLKComplicationServer

An object that manages the active complications for a given app.

class CLKComplication

Metadata about one of your custom complications.

class CLKComplicationTimelineEntry

A container for the complication template object to display and the time at which to display it.