Further explorations with Watch Face Push

This post is part of Wear OS Spotlight Week. Today, we're exploring the wonderful world of watch faces.

At Google I/O ‘25 we launched Watch Face Push, a new API aimed at enabling watch face marketplaces for watch and phone. Watch Face Push is now available to develop with and use on Wear OS 6 on devices such as the recently-launched Pixel Watch 4.

In this blog post, we’ll show how Watch Face Push (WFP) can be used in a whole host of other ways, including:

• Dynamically theming a watch face from a photo
• Presenting rich data or photos from online or connected data sources
• Complementing a phone app to drive engagement

The first example we’ll focus on is building a watch face with an accompanying phone app. It can apply a color theme based on a photo taken on the phone - perfect for matching your watch face to your outfit! And it’s perfect for demonstrating how Watch Face Push allows developers to bring dynamic data to the watch face.

Let’s go through some of the main techniques which combine together to make this possible:

The default watch face - bringing components together

A powerful feature of Watch Face Push is the default watch face feature. This allows the developer to provide a watch face that’s installed onto the Wear OS device at the same time as the overall app. This watch face is bundled as an APK and placed in the assets directory in the app.

The system checks for the presence of this APK as the app is being installed, and it checks for the validation key in the app’s manifest.

This enables you to deliver a single package that contains both the watch face and app components, whether that’s a full Wear OS app, where the app is the primary focus, or app components such as complication providers, where the watch face is the primary focus.

In our project structure, we define two modules, wear and watchface. By using a unified versionCode across both, we can keep the app and watch face versions in sync. We use Gradle to build the watch face and generate the validation token. This makes it easy to treat the watch face and the app as part of the same project.

Complication data sources - pipelines for data

Now that we’ve successfully supplied both watch face and app components together, we need a way to provide data.

The watch face is now able to rely on the presence of complication data sources provided by the app. For example, a surfing watch face could bundle with a water temperature complication. This can be set as the default on the watch face using DefaultProviderPolicy and is guaranteed to be present.

Taking it a step further, we can configure the complication to be non-customizable, so that the complication becomes more of a custom data source. We can then use the complication however the watch face may need:

<ComplicationSlot isCustomizable="FALSE" ... >
    <DefaultProviderPolicy
        defaultSystemProvider="NEXT_EVENT"
        defaultSystemProviderType="SHORT_TEXT"
        primaryProvider="<my_component_path>"
        primaryProviderType="SHORT_TEXT" />

   <!-- Rest of complication goes here -->

</ComplicationSlot>

In the case of our watch face, we define a SHORT_TEXT complication service PaletteComplicationService, which sends the following data:

TEXT: <space-delimited list of RGB hex values>
TITLE: CONFIGURED | NOT_CONFIGURED

By using two of the fields on SHORT_TEXT, we’re able to send our color palette to the watch face, along with an indicator of whether the app has been configured (more on why that is important later).

Extracting and manipulating complication data

We’ve demonstrated how using the guaranteed presence of the PaletteComplicationService allows us to ensure the watch face can receive our data, but we still need to define how to use and show the data within watch face elements.

Within the ComplicationSlot element on the watch face, these data items can be accessed as COMPLICATION.TEXT and COMPLICATION.TITLE respectively. The various functions such as abs() and subText() can be used to extract parts of these strings, or convert them into numeric types.

We combine this with the use of REFERENCE to define colors. We can retrieve these colors everywhere on the watch, including outside of the ComplicationSlot:

<ComplicationSlot ...
    isCustomizable="FALSE"
    x="0" y="0" width="1" height="1">
  <DefaultProviderPolicy
      defaultSystemProvider="NEXT_EVENT"
      defaultSystemProviderType="SHORT_TEXT"
    primaryProvider="com.example.palette/com.example.palette.complication.PaletteComplicationService"
      primaryProviderType="SHORT_TEXT" />
  <BoundingBox height="1" width="1" x="0" y="0" />
  <Complication> 

    <!-- Complication data source sends 3 RGB hex values, extract the first: -->
    <PartDraw x="0" y="0" width="1" height="1">
      <Transform target="tintColor" value="extractColorFromColors([COMPLICATION.TEXT], false, 0.0)" />
      <Reference source="tintColor" defaultValue="#000000" name="primary_color" />
      <Line startX="0" startY="0" endX="1" endY="1">
        <Stroke color="#000000" thickness="1" />
      </Line>
    </PartDraw>

    ...
  </Complication>
</ComplicationSlot>

This snippet illustrates creating a very small ComplicationSlot, which will simply serve as a pipeline for our data:

Within the complication, a placeholder PartDraw is created, and the extractColorFromColors() function is used to transform the PartDraw to the first color supplied by the complication. Using the Reference element, this color value is then available to the rest of the watch face as [REFERENCE.primary_color].

In the full example, two more PartDraw elements are used to provide the secondary_color and tertiary_color, simply providing the 0.5 and 1.0 index to the extractColorFromColors function instead of the 0.0 value.

Some of the samples illustrate how you can share different data types beyond just colors, such as numeric values.

Referencing complication data in the watch face

The primary_color, secondary_color and tertiary_color values can now be used elsewhere on the watch face, both in expressions and in transforms. In our example, we use the colors on the watch face hands:

<HourHand resource="hour" x="210" y="75" width="30" height="180" pivotX="0.5"
    pivotY="0.8333" tintColor="[REFERENCE.primary_color]">
</HourHand>

// Similar logic for the minute hand and second hand would refer to
// secondary_color and tertiary_color, respectively.

Keeping the watch face package up to date

A challenge with the default watch face approach is that if the app is updated, the watch face doesn’t automatically get updated with it, even if the new app bundle contains an updated watch face. To address that issue, the app uses a BroadcastReceiver to receive the MY_PACKAGE_REPLACED action. On receiving this, the app can then check whether the watch face is installed and is in need of an upgrade, using Watch Face Push to perform the upgrade if necessary.

For the MY_PACKAGE_REPLACED action to be received, the app must have been run at least once. For this reason, the sample watch faces include an example of ensuring the user launches the app: A “launch app” button is shown on the watch face if the app has not been launched before. This is achieved by using a Condition on the CONFIGURED or NOT_CONFIGURED status described earlier.

For many watch faces, this has an additional purpose: it allows the user to enable additional components, such as a photo downloader in the Photo Album example shown here. You can also use the “first launch” experience to prompt the user to grant permissions or to sign in.

Working with other app components

While the complication data source is the conduit for data, and is the common component in all the examples, the following Android APIs work with complications to achieve the desired functionality:

• WearableListenerService - both the PaletteWatchFace and the FootballWatchFace have phone companion apps, and the Data Layer is used to send data to the watch. Once received by the WearableListenerService, you can proactively update the data on the watch face using ComplicationDataSourceUpdateRequester.
• WorkManager - the PhotoAlbumWatchFace example demonstrates how to retrieve photos from an online photo service. WorkManager is used for this, using Constraints to only download images while the device is being charged.
• ForegroundService - the DeviceDataWatchFace illustrates using a ForegroundService to obtain data from a connected Bluetooth device which is then visualized on the watch face.

Check out the full source for these examples. We look forward to seeing what you can create!