A watch face is a [service](https://developer.android.com/guide/components/services)
packaged in a [Wear OS app](https://developer.android.com/training/wearables/apps).
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](https://developer.android.com/studio) for Wear OS development, as
it provides project setup, library inclusion, and packaging conveniences.

Complete the following steps to
[create a project](https://developer.android.com/studio/projects/create-project#StartAProject)
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](https://developer.android.com/reference/kotlin/androidx/wear/watchface/package-summary); see the
[code sample](https://github.com/android/wear-os-samples/tree/main/WatchFaceKotlin) 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](https://developer.android.com/reference/android/support/wearable/watchface/package-summary) 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:  

```xml
<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](https://developer.android.com/training/articles/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](https://developer.android.com/training/articles/direct-boot#access).

<br />

## Implement the service and callback methods

Watch faces in Wear OS are implemented as a
[`WatchFaceService`](https://developer.android.com/reference/kotlin/androidx/wear/watchface/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:  

### Kotlin

```kotlin
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 = // ...

}
```

## Register the watch face service

After you implement the watch face service, register the implementation in the manifest
file of the wearable app. When users install this app, the system uses the information about
the service to make the watch face available in the [Wear OS companion app](https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en) and in the watch face picker on the wearable device.

The following sample shows how to register a watch face implementation
under the [`<application>`](https://developer.android.com/guide/topics/manifest/application-element) element:  

```xml
<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>
```

The Wear OS by Google companion app and the watch face picker on the wearable device use the preview
image defined by the `com.google.android.wearable.watchface.preview_circular` metadata entry when
presenting users with all the watch faces installed on the device. To obtain this drawable,
run the watch face on your Wear OS device or in an emulator instance and
[take a screenshot](https://developer.android.com/studio/debug/am-screenshot). On Wear
devices with hdpi screens, the preview image is typically 320x320 pixels in size.

The `android.service.wallpaper` metadata entry specifies the
`watch_face.xml` resource file, which contains a `wallpaper`
element, as shown in the following sample:  

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

Your wearable app can contain more than one watch face. You must add a service entry to the
manifest file of the wearable app for each of your watch face implementations.

## Related resources


Refer to the following related resources:

- [WatchFaceKotlin sample](https://github.com/android/wear-os-samples/tree/deprecated/WatchFaceKotlin)