Build a watch face service

A watch face is a service packaged in a Wear OS app. When a user selects an available watch face, the watch face displays and the service callback methods are invoked.

When a user installs a Wear app that has watch faces, the watch faces are available on the watch using the watch face selector. Alternatively, the user can select a watch face from a companion app on the paired phone.

This page describes how to configure a Wear OS project to include watch faces and how to implement a watch face service.

Create a watch face project

Note: We recommend that you use Android Studio for Wear OS development, as it provides project setup, library inclusion, and packaging conveniences.

Complete the following steps to create a project in Android Studio for your watch face:

1. Click File > New > New project.
2. In the Select a project template window, select the Wear tab, then select Watch Face from the list of options and click Next.
3. In the Configure your project window, accept the default values and click Finish.

Android Studio creates a project with an app module for your watch face service.

Dependencies

Android Studio automatically adds the required dependencies in your build.gradle files. Included in the dependencies is the AndroidX watch face library; see the code sample on GitHub for details about this library.

Wearable support library API reference

The reference documentation provides detailed information about the classes you use to implement watch faces. Browse the API reference documentation for the Wearable support library.

Declare permissions

A watch face requires the WAKE_LOCK permission. Add the following permission to the manifest files of both the Wear OS app and the mobile phone app under the manifest element:

<manifest ...>
    <uses-permission
        android:name="android.permission.WAKE_LOCK" />

    <!-- Required for complications to receive complication data and open the provider chooser. -->
    <uses-permission
        android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
    ...
</manifest>

Support direct-boot

You must make your watchface available before user-unlock by following Direct Boot guidance:

1. Set android:directBootAware attribute to true for your service in your manifest.
2. Your watch face should store information in device encrypted storage.

Implement the service and callback methods

Watch faces in Wear OS are implemented as a WatchFaceService. Implementing a WatchFaceService requires creating three objects: a UserStyleSchema, a ComplicationSlotsManager, and a WatchFace.

These three objects are specified by overriding three abstract methods from WatchFaceService, shown in the following example:

class CustomWatchFaceService : WatchFaceService() {

    /**
     * The specification of settings the watch face supports.
     * This is similar to a database schema.
     */
    override fun createUserStyleSchema(): UserStyleSchema = // ...

    /**
     * The complication slot configuration for the watchface.
     */
    override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager = // ...

    /**
     * The watch face itself, which includes the renderer for drawing.
     */
    override suspend fun createWatchFace(
        surfaceHolder: SurfaceHolder,
        watchState: WatchState,
        complicationSlotsManager: ComplicationSlotsManager,
        currentUserStyleRepository: CurrentUserStyleRepository
    ): WatchFace = // ...

}

<service
    android:name=".AnalogWatchFaceService"
    android:label="@string/analog_name"
    android:permission="android.permission.BIND_WALLPAPER" >
    <meta-data
        android:name="android.service.wallpaper"
        android:resource="@xml/watch_face" />
    <meta-data
        android:name="com.google.android.wearable.watchface.preview_circular"
        android:resource="@drawable/preview_analog_circular" />
    <intent-filter>
        <action android:name="android.service.wallpaper.WallpaperService" />
        <category
            android:name=
            "com.google.android.wearable.watchface.category.WATCH_FACE" />
    </intent-filter>
</service>

<?xml version="1.0" encoding="UTF-8"?>
<wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />