Watch Face Format のセットアップ

このガイドでは、Watch Face Format を使用してウォッチフェイスを構成するのに必要なツールの手順、プロジェクト構造に関する推奨事項、その構造を作成するツールを適用するための手順ガイドを示します。

前提条件

Watch Face Format の使用に対する開発環境を整えるには、次のセットアップ手順を完了してください。

  1. Android 14（API レベル 34）以降に対応する SDK をインストールします。ウォッチフェイスがバージョン 2 に固有の機能や動作に依存していない場合は、代わりに Android 13（API レベル 33）の SDK をインストールできます。

    この SDK には、aapt2 や android.jar など、その他の必要なツールが含まれています。

  2. または、これらのツールを提供している Android Studio をインストールします。

プロジェクトの構造

Watch Face Format を使用するカスタム ウォッチフェイスを作成する場合、カスタム ウォッチフェイス ファイルを含む Android App Bundle は、Wear OS アプリのロジックを含む Android App Bundle から完全に分離する必要があります。Google Play を含む一部のアプリストアでは、Wear OS ロジックとカスタム ウォッチフェイスの両方が含まれる Android App Bundle はアップロードできません。

ウォッチフェイス バンドルを作成する

ウォッチフェイス ファイルを備えた Android App Bundle を作成するには、以下のセクションに示す手順を完了してください。

Watch Face Format の使用を宣言する

新しいアプリのマニフェスト ファイル（AndroidManifest.xml）に、Watch Face Format の使用を示すアプリ プロパティを追加します。Wear OS 5 以降を搭載したデバイスでウォッチフェイスへのアクセスを制限しない場合は、バージョン 2 をサポートするウォッチフェイス APK とバージョン 1 をサポートするウォッチフェイス APK を 2 つ作成します。詳しくは、アプリのバージョンを設定する方法をご覧ください。

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

ウォッチフェイスのメタデータを宣言する

アプリの res/xml リソース ディレクトリに watch_face_info.xml という新しいファイルを作成します。ここでは、ウォッチフェイスのメタデータを定義します。

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

このファイルのフィールドは、次の詳細を表しています。

Preview
ウォッチフェイスのプレビュー画像を含むドローアブルを参照します。
Category

ウォッチフェイスのカテゴリを定義します。文字列か、@string/ref_name などの文字列への参照を指定する必要があります。各デバイス メーカーは、それぞれ独自のウォッチフェイス カテゴリのセットを定義できます。

デフォルト値: empty_category_meta。ウォッチフェイス選択ツールビューの一番下に、このウォッチフェイスを他の「空のカテゴリ」のウォッチフェイスと一緒にグループ化します。

AvailableInRetail

デバイスの販売店デモモードでウォッチフェイスを使用できるかどうか。 ブール値、または @bool/watch_face_available_in_retail などのブール値への参照である必要があります。

デフォルト値: false

MultipleInstancesAllowed

ウォッチフェイスに複数のお気に入りを登録できるかどうか。ブール値、または @bool/watch_face_multiple_instances_allowed などのブール値への参照である必要があります。

デフォルト値: false

Editable

ウォッチフェイスが編集可能かどうか（つまり、ウォッチフェイスの設定や固定されていないウォッチフェイスの追加機能が 1 つ以上あるかどうか）。これは、お気に入りリストにあるウォッチフェイスの [編集] ボタンを表示または非表示にするために使用されます。

デフォルト値: false

ウォッチフェイス名を宣言する

アプリのマニフェスト ファイル（AndroidManifest.xml）では、android:label 属性をウォッチフェイスの名前に設定します。

<application android:label="@string/watch_face_name" >

ウォッチフェイスの形状に関するサポートを宣言する（省略可）

この手順は、さまざまなサイズのウォッチフェイスで異なる動作をサポートする場合にのみ必要です。ウォッチフェイスがスマートウォッチのサイズに合わせてスケーリングされる場合は、この手順をスキップできます。

アプリの res/xml リソース ディレクトリで、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>

ウォッチフェイスの詳細を宣言する

アプリの res/raw リソース ディレクトリで、ウォッチフェイスの形状に関するサポートを宣言する際に使う file 属性値に対応したファイルを作成します。

ここで、ウォッチフェイスの形状ごとにウォッチフェイスの外観と動作を定義します。シェイプ ファイルを定義していない場合は、watchface.xml という 1 つのファイルを作成するだけで済みます。

このページの例を使うと、未加工の XML ファイルは次のようになります。

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

ルート要素は常に 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>

ウォッチフェイスのパブリッシャーを特定する（省略可）

必要に応じて、アプリのマニフェスト ファイルで、ウォッチフェイスのパブリッシャーの特定に使用できる任意の文字列、または使用するツール名とバージョンを宣言します。

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="{toolName}-{toolVersion}" />
</application>

ウォッチフェイスの正確性とパフォーマンスを確認する

開発中および Google Play にアップロードする前に、検証ツールを使用して、ウォッチフェイスにエラーがないこと、メモリ使用量の推奨事項に準拠していることを確認します。

ウォッチフェイスの App Bundle をビルドする

ウォッチフェイスを含む Android App Bundle をビルドするには、Gradle ビルドシステムを使用します。詳しくは、Gradle を使用してアプリをビルドする方法をご覧ください。

これは GitHub のサンプルで示されています。