ウォッチフェイスサービスを構築する

ウォッチフェイスは、Wear OS アプリにパッケージされているサービスです。ユーザーが利用可能なウォッチフェイスを選択すると、ウォッチフェイスが表示され、サービスのコールバックメソッドが呼び出されます。

ウォッチフェイスがパッケージされている Wear OS アプリをインストールすると、ユーザーはスマートウォッチでウォッチフェイス選択ツールを使用してウォッチフェイスを選択できます。また、ペア設定されているスマートフォンのコンパニオンアプリでも、ウォッチフェイスを選択できます。

このページでは、Wear OS プロジェクトを設定してウォッチフェイスを追加する方法と、ウォッチフェイスサービスを実装する方法について説明します。

以下の関連リソースをご覧ください。

インタラクティブなウォッチフェイス

WatchFace サンプル

ウォッチフェイスプロジェクトを作成する

Android Studio でウォッチフェイスのプロジェクトを作成するには:

[File] > [New] > [New project] をクリックします。
[Create Android Project] ウィンドウでデフォルト値を受け入れ、[Next] をクリックします。
[Target Android Devices] ウィンドウで [Wear] オプションのみを選択し、SDK バージョンのリストで使用可能な最新のバージョンを選択して、[Next] をクリックします。
[Add an Activity to Wear] ウィンドウで [Watch Face] を選択して、[Next] をクリックします。
[Configure Activity] ウィンドウでデフォルト値を受け入れ、[Finish] をクリックします。

Android Studio は、ウォッチフェイスサービス用の app モジュールを使用してプロジェクトを作成します。Android Studio のプロジェクトについて詳しくは、プロジェクトの作成をご覧ください。

依存関係

ウェアラブルサポートライブラリには、拡張してウォッチフェイス実装の作成に使用する必須のクラスが含まれています。Wearable Data Layer API を使用してコンパニオンデバイスとウェアラブルの間でデータアイテムを同期するには、Google Play 開発者サービスのクライアントライブラリ（play-services と play-services-wearable）が必要です。

上記の手順に従ってプロジェクトを作成すると、必要なエントリが Android Studio によって build.gradle ファイルに自動的に追加されます。

ウェアラブルサポートライブラリ API リファレンス

リファレンスドキュメントには、ウォッチフェイスを実装する際に使用するクラスについての詳細な情報が記載されています。ウェアラブルサポートライブラリについては、API リファレンスドキュメントをご覧ください。

注: Wear OS の開発には Android Studio を使用することをおすすめします。Android Studio では、プロジェクトのセットアップ、ライブラリのインクルード、パッケージングを容易に行うことができます。

権限を宣言する

ウォッチフェイスには WAKE_LOCK 権限が必要です。Wear OS アプリ（ウェアラブルアプリ）とモバイル（スマートフォン）アプリの両方のマニフェストファイルで、manifest 要素に以下の権限を追加します。

    <manifest ...>
        <uses-permission
            android:name="android.permission.WAKE_LOCK" />

        <!-- Required for complications to receive complication data and open the provider chooser. -->
        <uses-permission
            android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
        ...
    </manifest>

注意: ハンドヘルドアプリには、ウェアラブルアプリで宣言したすべての権限を含める必要があります。

サービスとコールバックメソッドを実装する

Wear OS のウォッチフェイスはサービスとして実装されます。ウォッチフェイスがアクティブな場合、時刻が変わったときや、重要なイベントが発生したとき（たとえば、常に画面表示モードに切り替わったときや新しい通知を受け取ったとき）に、システムはサービス内のメソッドを呼び出します。サービスの実装は、更新された時刻とその他の関連データを使用して、ウォッチフェイスを画面上に描画します。

ウォッチフェイスを実装するには、CanvasWatchFaceService クラスと CanvasWatchFaceService.Engine クラスを拡張し、次に CanvasWatchFaceService.Engine クラスのコールバックメソッドをオーバーライドします。これらのクラスはウェアラブルサポートライブラリに含まれています。

次のスニペットは、実装する必要がある主なメソッドの概要を示しています。

Kotlin

    class AnalogWatchFaceService : CanvasWatchFaceService() {

        override fun onCreateEngine(): Engine {
            /* provide your watch face implementation */
            return Engine()
        }

        /* implement service callback methods */
        inner class Engine : CanvasWatchFaceService.Engine() {

            override fun onCreate(holder: SurfaceHolder) {
                super.onCreate(holder)
                /* initialize your watch face */
            }

            override fun onPropertiesChanged(properties: Bundle?) {
                super.onPropertiesChanged(properties)
                /* get device features (burn-in, low-bit ambient) */
            }

            override fun onTimeTick() {
                super.onTimeTick()
                /* the time changed */
            }

            override fun onAmbientModeChanged(inAmbientMode: Boolean) {
                super.onAmbientModeChanged(inAmbientMode)
                /* the wearable switched between modes */
            }

            override fun onDraw(canvas: Canvas, bounds: Rect) {
                /* draw your watch face */
            }

            override fun onVisibilityChanged(visible: Boolean) {
                super.onVisibilityChanged(visible)
                /* the watch face became visible or invisible */
            }
        }
    }

Java

    public class AnalogWatchFaceService extends CanvasWatchFaceService {

        @Override
        public Engine onCreateEngine() {
            /* provide your watch face implementation */
            return new Engine();
        }

        /* implement service callback methods */
        private class Engine extends CanvasWatchFaceService.Engine {

            @Override
            public void onCreate(SurfaceHolder holder) {
                super.onCreate(holder);
                /* initialize your watch face */
            }

            @Override
            public void onPropertiesChanged(Bundle properties) {
                super.onPropertiesChanged(properties);
                /* get device features (burn-in, low-bit ambient) */
            }

            @Override
            public void onTimeTick() {
                super.onTimeTick();
                /* the time changed */
            }

            @Override
            public void onAmbientModeChanged(boolean inAmbientMode) {
                super.onAmbientModeChanged(inAmbientMode);
                /* the wearable switched between modes */
            }

            @Override
            public void onDraw(Canvas canvas, Rect bounds) {
                /* draw your watch face */
            }

            @Override
            public void onVisibilityChanged(boolean visible) {
                super.onVisibilityChanged(visible);
                /* the watch face became visible or invisible */
            }
        }
    }

CanvasWatchFaceService クラスは、View.invalidate() メソッドに似た無効化メカニズムを提供します。システムにウォッチフェイスを再描画させたい場合は、実装のあらゆる場所で invalidate() メソッドを呼び出すことができます。invalidate() メソッドは、メイン UI スレッドでのみ使用できます。別のスレッドからキャンバスを無効化するには、postInvalidate() メソッドを呼び出します。

CanvasWatchFaceService.Engine クラスのメソッドの実装について詳しくは、ウォッチフェイスを描画するをご覧ください。

ウォッチフェイスサービスを登録する

ウォッチフェイスサービスを実装したら、ウェアラブルアプリのマニフェストファイルに実装を登録します。ユーザーがこのアプリをインストールすると、システムはサービスに関する情報を使用して、Wear OS のコンパニオンアプリと、ウェアラブルデバイスのウォッチフェイス選択ツールで、ウォッチフェイスを選択できるようにします。

次のスニペットは、application 要素にウォッチフェイスの実装を登録する方法を示しています。

    <service
        android:name=".AnalogWatchFaceService"
        android:label="@string/analog_name"
        android:permission="android.permission.BIND_WALLPAPER" >
        <meta-data
            android:name="android.service.wallpaper"
            android:resource="@xml/watch_face" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview"
            android:resource="@drawable/preview_analog" />
        <meta-data
            android:name="com.google.android.wearable.watchface.preview_circular"
            android:resource="@drawable/preview_analog_circular" />
        <intent-filter>
            <action android:name="android.service.wallpaper.WallpaperService" />
            <category
                android:name=
                "com.google.android.wearable.watchface.category.WATCH_FACE" />
        </intent-filter>
    </service>

Wear OS のコンパニオンアプリと、ウェアラブルデバイスのウォッチフェイス選択ツールは、デバイスにインストールされているすべてのウォッチフェイスをユーザーに提示する際に、com.google.android.wearable.watchface.preview メタデータエントリで定義されているプレビュー画像を使用します。このドローアブルを取得するには、Wear OS デバイスまたはエミュレータインスタンスでウォッチフェイスを実行し、スクリーンショットを撮ります。hdpi 画面を持つ Wear OS デバイスでは、プレビュー画像のサイズは通常、320 x 320 ピクセルです。

円形のデバイスでは外観が大きく異なるウォッチフェイスの場合は、円形と正方形の両方のプレビュー画像を指定できます。円形のプレビュー画像を指定するには、com.google.android.wearable.watchface.preview_circular メタデータエントリを使用します。ウォッチフェイスに両方のプレビュー画像を指定した場合、コンパニオンアプリと、ウェアラブルのウォッチフェイス選択ツールは、スマートウォッチの形状に応じて適切なプレビュー画像を表示します。円形のプレビュー画像が含まれていない場合、正方形と円形の両方のデバイスで正方形のプレビュー画像が使用されます。正方形のプレビュー画像は、円形のデバイスでは円形に切り取られます。

android.service.wallpaper メタデータエントリには、wallpaper 要素を含む watch_face.xml リソースファイルを指定します。

    <?xml version="1.0" encoding="UTF-8"?>
    <wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />

ウェアラブルアプリには複数のウォッチフェイスを含めることができます。そのためには、ウォッチフェイスの実装ごとに、ウェアラブルアプリのマニフェストファイルにサービスエントリを追加する必要があります。

ウォッチフェイスの設計

ウォッチフェイスの描画

ウォッチフェイス サービスを構築する

ウォッチフェイス プロジェクトを作成する