Watch Face Format setup

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.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<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"
        ...>
        <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>
    <!-- Only "Preview" is required. -->
    <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 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>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

Declare watch face details

In your app's res/raw resources directory, create files corresponding to the file attribute values used when you declare support for watch face shapes.

This is where you 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 page, the raw XML files would be:

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml
  • res/raw/watchface_rectangle.xml

The root element is always WatchFace:

<WatchFace width="450" height="450" clipShape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

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="{toolName}-{toolVersion}" />
</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.