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 13 (API level 33) or higher. The SDK contains other required tools, including aapt2 and android.jar.
  2. Install the bundletool command-line program.
  3. Sign the debug version of the app that contains your watch face design. You can generate a signed Android App Bundle in Android Studio, or you can sign your debug build manually.

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:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <application ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="1" />
    </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 reference 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

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

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

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" shape="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>

Build your watch face's app bundle

To build the Android App Bundle that contains your watch face, use the bundletool. Learn more about how to build an app using bundletool.

See the GitHub samples for examples of preparing your app bundle for publishing, as well as the validator tools for checking correctness before submitting to Google Play.