**Note** : This page shows you a step of the process for manually managing your
watch face configuration. If you want to design your watch face using a WYSIWYG
(what you see is what you get) style tool instead, check out the [Watch Face
Studio](https://developer.samsung.com/watch-face-studio/user-guide/index.html) guides first.

This guide includes steps on the tools that you need to configure a watch face
using the Watch Face Format, some suggestions on project structure, and a
step-by-step guide to applying the tools to create that structure.

## Prerequisites

To prepare your development environment for using the Watch Face Format,
complete the following setup steps:

1. Install the SDK for Android 14 (API level 34) or higher. If your watch face
   doesn't rely on [features or behavior specific to version 2](https://developer.android.com/training/wearables/wff/features#v2), you can
   install the SDK for Android 13 (API level 33) instead.

   The SDK contains other required tools, including `aapt2` and `android.jar`.
2. *Alternatively* , install [Android Studio](https://developer.android.com/studio), which can also provide these
   tools.

## Project structure

When you create a custom watch face that uses the Watch Face Format, the Android
App Bundle that includes the custom watch face file must be completely separate
from the Android App Bundle that contains your Wear OS app's logic. Some app
stores, including Google Play, prevent you from uploading an Android App Bundle
that includes both Wear OS logic and a custom watch face.

## Create watch face bundle

To create an Android App Bundle that features a watch face file, complete the
steps shown in the following sections.

### Declare use of Watch Face Format

In your new app's manifest file (`AndroidManifest.xml`), add an application
property that indicates your use of the Watch Face Format. Unless you want to
restrict access to your watch face for devices running Wear OS 5 or higher,
create 2 different watch face APKs, one that supports version 2 and one that
supports version 1. Learn more about how to configure [versions](https://developer.android.com/build/configure-apk-splits) of your app.  

    <manifest ...>
        <!--
            Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
            1 of WFF
        -->
        <uses-sdk
            android:minSdkVersion="34"
            android:targetSdkVersion="34" />

        <!--
            WFF is a resource-only format, so the hasCode attribute should be set to
            false to reflect this.
        -->
        <application
            android:label="@string/watch_face_name"
            android:hasCode="false"
            ...>
            <meta-data android:name="com.google.android.wearable.standalone"
                android:value="true" />
            <property
                android:name="com.google.wear.watchface.format.version"
                android:value="2" />
        </application>
    </manifest>

### Declare watch face metadata

In your app's `res/xml` resources directory, create a new file called
`watch_face_info.xml`. This is where you define your watch face's metadata:  

    <?xml version="1.0" encoding="utf-8"?>
    <WatchFaceInfo>

        <Preview value="@drawable/watch_face_preview" />
        <Category value="CATEGORY_EMPTY" />
        <AvailableInRetail value="true" />
        <MultipleInstancesAllowed value="true" />
        <Editable value="true" />
    </WatchFaceInfo>

The fields in this file represent the following details:

`Preview`
:   References the drawable that contains a preview image of the watch face.

`Category`

:   Defines the watch face's category. Must be a string or a reference to a
    string, such as `@string/ref_name`. Each device manufacturer can define its own
    set of watch face categories.

    Default value: `empty_category_meta`, which groups this watch face together
    with other "empty category" watch faces at the bottom of the watch face
    picker view.

`AvailableInRetail`

:   Whether the watch face is available in the device's [retail demo
    mode](https://source.android.com/docs/core/display/retail-mode). Must be a boolean value or a reference to a boolean value
    such as `@bool/watch_face_available_in_retail`.

    Default value: `false`

`MultipleInstancesAllowed`

:   Whether the watch face can have multiple favorites. Must be a boolean value,
    or a reference to a boolean value such as
    `@bool/watch_face_multiple_instances_allowed`.

    Default value: `false`

`Editable`

:   Whether the watch face is *editable* , which means that the watch face has a
    setting or at least one non-fixed [complication](https://developer.android.com/training/wearables/tiles/complications). This is used to show or
    hide the **Edit** button for the watch face in the favorites list.

    Default value: false

### Declare watch face name

In your app's manifest file (`AndroidManifest.xml`), set the `android:label`
attribute to the name of your watch face:  

    <application android:label="@string/watch_face_name" >

### Declare watch face details

The structure of a basic WFF watch face document is as follows:  

    <WatchFace width="450" height="450">
      <Scene>
        <!-- Content to be rendered -->
      </Scene>
    </WatchFace>

Create this XML file as `res/raw/watchface.xml` when constructing your watch
face, if working with a single watch face. To support different
screen shapes and sizes, [declare support for multiple shapes and
sizes](https://developer.android.com/training/wearables/wff/setup#declare-shape-support).

The root element is always [`WatchFace`](https://developer.android.com/training/wearables/wff/watch-face). The `height` and `width` define the
extent of the coordinate space for use in your watch face, and the watch face
is scaled to fit the device it is being used on; `height` and `width` don't
represent actual pixels.

The Watch Face Format organizes several details about your watch face:

- *Metadata*, such as the time and step count that's shown in your watch face's preview image.
- *User configurations* , such as different color themes for your watch face, user-toggleable elements, and a choice among several elements. Watch Face Format version 2 introduces *flavors*, which can appear within a user configuration. Each flavor specifies a preset user configuration, specifying the type and style of elements that appear with the time in your watch face. These presets make it easier for you to create groups of elements that are visually pleasing. In the Wear OS companion app, users see your watch face's different flavors along a scrollable row.
- A *scene* which contains the visual elements of a watch face. Elements that appear closer to the end of the scene appear on top of other elements, so the typical order is as follows:
  - The hands for an analog clock or the text for a digital clock
  - Complications that show additional information, such as the day of the week or a user's step count
  - Other graphics that provide visual interest or decorations for the watch face, such as an image of a campsite
- *Groups* of elements, which let you modify multiple elements at the same time. You can create *variants* of these groups within a scene, which lets you selectively hide or modify content when the system enters a power-saving ambient mode.

Attributes are strongly typed and have guidelines around frequency and valid
values to avoid most sources of errors when creating a watch face.
| **Note:** As you configure your watch face, [optimize its memory usage](https://developer.android.com/training/wearables/wff/memory-usage).

### Declare support for watch face shapes (optional)

This step is only necessary if you want to support different behavior for
different sizes of watch faces. You can skip this step if you are happy for your
watch face to scale with the size of the watch.

In your app's `res/xml` resources directory, declare the set of watch face
shapes that you support in `watch_face_shapes.xml`:  

```xml
<WatchFaces>

    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>

    <!-- Remove any references to rectangular watch faces -->
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>
```

Then, define your watch face appearance and behavior for each watch face shape.
If you did not define a shapes file, then you only need to create one file,
`watchface.xml`.

Using the example from this section, the raw XML files would be:

- `res/raw/watchface.xml`
- `res/raw/watchface_large_circle.xml`
- `res/raw/watchface_rectangle.xml`

### Identify watch face publisher (optional)

Optionally, in your app's manifest file, declare an arbitrary string that you
can use to identify the publisher of the watch face, or the tool name and
version that you're using:  

    <application ...>
        ...
        <property
            android:name="com.google.wear.watchface.format.publisher"
            android:value="<var>{toolName}-{toolVersion}</var>" />
    </application>

## Check your watch face correctness and performance

During development, and before uploading to Google Play, use the [validator
tools](https://github.com/google/watchface) to check that your watch face is free from errors, and
that it complies with memory usage recommendations.

- Learn more about [optimizing memory usage](https://developer.android.com/training/wearables/wff/memory-usage) and [checking memory usage](https://github.com/google/watchface/tree/main/play-validations) in preparation for publishing.
- Learn more about using the [XML validator](https://github.com/google/watchface/tree/main/third_party/wff) as part of your development cycle.

## Build your watch face app bundle

To build the Android App Bundle that contains your watch face, use the Gradle
build system. Learn more about how to [build an app using Gradle](https://developer.android.com/build#build-files).

This is demonstrated in the [GitHub samples](https://github.com/android/wear-os-samples/tree/main/WatchFaceFormat).

## Recommended for you

- Note: link text is displayed when JavaScript is off
- [AAPT2](https://developer.android.com/tools/aapt2)
- [Jetpack Compose basics](https://developer.android.com/codelabs/jetpack-compose-basics)
- [Getting Started with CameraX](https://developer.android.com/codelabs/camerax-getting-started)