Watch Face Format setup

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 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, 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, 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 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. 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. 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.

The root element is always WatchFace. 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.

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:

<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 to check that your watch face is free from errors, and that it complies with memory usage recommendations.

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.

This is demonstrated in the GitHub samples.