Posted by Garan Jenkin – Developer Relations Engineer

This submit is a part of Put on OS Highlight Week. Right now, we’re exploring the fantastic world of watch faces.

At Google I/O ‘25 we launched Watch Face Push, a brand new API aimed toward enabling watch face marketplaces for watch and cellphone. Watch Face Push is now obtainable to develop with and use on Put on OS 6 on units such because the recently-launched Pixel Watch 4.

On this weblog submit, we’ll present how Watch Face Push (WFP) can be utilized in a complete host of different methods, together with:

• Dynamically theming a watch face from a photograph
• Presenting wealthy knowledge or pictures from on-line or linked knowledge sources
• Complementing a cellphone app to drive engagement

The primary instance we’ll deal with is constructing a watch face with an accompanying cellphone app. It will possibly apply a coloration theme primarily based on a photograph taken on the cellphone – good for matching your watch face to your outfit! And it’s good for demonstrating how Watch Face Push permits builders to deliver dynamic knowledge to the watch face.

Let’s undergo a number of the important strategies which mix collectively to make this attainable:

The default watch face – bringing parts collectively

A strong function of Watch Face Push is the default watch face function. This enables the developer to supply a watch face that’s put in onto the Put on OS gadget concurrently the general app. This watch face is bundled as an APK and positioned within the property listing within the app.

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

This allows you to ship a single package deal that accommodates each the watch face and app parts, whether or not that’s a full Put on OS app, the place the app is the first focus, or app parts equivalent to complication suppliers, the place the watch face is the first focus.

In our undertaking construction, we outline two modules, put on and watchface. Through the use of a unified versionCode throughout each, we will maintain the app and watch face variations in sync. We use Gradle to construct the watch face and generate the validation token. This makes it simple to deal with the watch face and the app as a part of the identical undertaking.

Complication knowledge sources – pipelines for knowledge

Now that we’ve efficiently provided each watch face and app parts collectively, we want a method to supply knowledge.

The watch face is now capable of depend on the presence of complication knowledge sources offered by the app. For instance, a browsing watch face may bundle with a water temperature complication. This may be set because the default on the watch face utilizing DefaultProviderPolicy and is assured to be current.

Taking it a step additional, we will configure the complication to be non-customizable, in order that the complication turns into extra of a customized knowledge supply. We are able to then use the complication nevertheless the watch face might have:

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

   <!-- Relaxation of complication goes right here -->

</ComplicationSlot>

Within the case of our watch face, we outline a SHORT_TEXT complication service PaletteComplicationService, which sends the next knowledge:

TEXT: <house-delimited checklist of RGB hex values>
TITLE: CONFIGURED | NOT_CONFIGURED

Through the use of two of the fields on SHORT_TEXT, we’re capable of ship our coloration palette to the watch face, together with an indicator of whether or not the app has been configured (extra on why that’s essential later).

Extracting and manipulating complication knowledge

We’ve demonstrated how utilizing the assured presence of the PaletteComplicationService permits us to make sure the watch face can obtain our knowledge, however we nonetheless have to outline easy methods to use and present the information inside watch face components.

Throughout the ComplicationSlot aspect on the watch face, these knowledge objects could be accessed as COMPLICATION.TEXT and COMPLICATION.TITLE respectively. The varied features equivalent to abs() and subText() can be utilized to extract elements of those strings, or convert them into numeric varieties.

We mix this with the usage of REFERENCE to outline colours. We are able to retrieve these colours in every single place on the watch, together with exterior of the ComplicationSlot:

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

    <!-- Complication knowledge supply sends 3 RGB hex values, extract the first: -->
    <PartDraw x="0" y="0" width="1" top="1">
      <Rework goal="tintColor" worth="extractColorFromColors([COMPLICATION.TEXT], false, 0.0)" />
      <Reference supply="tintColor" defaultValue="#000000" title="primary_color" />
      <Line startX="0" startY="0" endX="1" endY="1">
        <Stroke coloration="#000000" thickness="1" />
      </Line>
    </PartDraw>

    ...
  </Complication>
</ComplicationSlot>

This snippet illustrates creating a really small ComplicationSlot, which can merely function a pipeline for our knowledge:

Throughout the complication, a placeholder PartDraw is created, and the extractColorFromColors() perform is used to remodel the PartDraw to the primary coloration provided by the complication. Utilizing the Reference aspect, this coloration worth is then obtainable to the remainder of the watch face as [REFERENCE.primary_color].

Within the full instance, two extra PartDraw components are used to supply the secondary_color and tertiary_color, merely offering the 0.5 and 1.0 index to the extractColorFromColors perform as a substitute of the 0.0 worth.

A few of the samples illustrate how one can share completely different knowledge varieties past simply colours, equivalent to numeric values.

Referencing complication knowledge within the watch face

The primary_color, secondary_color and tertiary_color values can now be used elsewhere on the watch face, each in expressions and in transforms. In our instance, we use the colours on the watch face arms:

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

// Comparable logic for the minute hand and second hand would check with
// secondary_color and tertiary_color, respectively.

Retaining the watch face package deal updated

A problem with the default watch face strategy is that if the app is up to date, the watch face doesn’t robotically get up to date with it, even when the brand new app bundle accommodates an up to date watch face. To handle that subject, the app makes use of a BroadcastReceiver to obtain the MY_PACKAGE_REPLACED motion. On receiving this, the app can then verify whether or not the watch face is put in and is in want of an improve, utilizing Watch Face Push to carry out the improve if essential.

For the MY_PACKAGE_REPLACED motion to be acquired, the app will need to have been run not less than as soon as. Because of this, the pattern watch faces embrace an instance of making certain the consumer launches the app: A “launch app” button is proven on the watch face if the app has not been launched earlier than. That is achieved through the use of a Situation on the CONFIGURED or NOT_CONFIGURED standing described earlier.

For a lot of watch faces, this has an extra objective: it permits the consumer to allow extra parts, equivalent to a photograph downloader within the Photograph Album instance proven right here. You may also use the “first launch” expertise to immediate the consumer to grant permissions or to sign up.

Working with different app parts

Whereas the complication knowledge supply is the conduit for knowledge, and is the widespread element in all of the examples, the next Android APIs work with problems to realize the specified performance:

• WearableListenerService – each the PaletteWatchFace and the FootballWatchFace have cellphone companion apps, and the Knowledge Layer is used to ship knowledge to the watch. As soon as acquired by the WearableListenerService, you possibly can proactively replace the information on the watch face utilizing ComplicationDataSourceUpdateRequester.
• WorkManager – the PhotoAlbumWatchFace instance demonstrates easy methods to retrieve pictures from an internet photograph service. WorkManager is used for this, utilizing Constraints to solely obtain photos whereas the gadget is being charged.
• ForegroundService – the DeviceDataWatchFace illustrates utilizing a ForegroundService to acquire knowledge from a linked Bluetooth gadget which is then visualized on the watch face.

Try the full supply for these examples. We stay up for seeing what you possibly can create!