Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ウォッチフェイスプッシュ用に Wear OS アプリを構成する

ウォッチフェイスプッシュを使用すると、アプリで Wear OS デバイスのウォッチフェイスを管理できます。これには、ウォッチフェイスの追加、更新、削除、アクティブなウォッチフェイスの設定が含まれます。Watch Face Push API を使用するように Wear OS アプリを設定します。

設定

build.gradle.kts ファイルに androidx.wear.watchfacepush:watchfacepush 依存関係を含めます。

AndroidManifest.xml に次の行を追加します。

<!-- Required to use the Watch Face Push API.  -->
<uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />AndroidManifest.xml

マネージャーインスタンスへの参照を取得する

WatchFacePushManager のインスタンスを取得します。

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)WatchFacePush.kt

WatchFacePushManager は、Watch Face Push とやり取りするためのすべてのメソッドへのアクセスを提供します。

スロットを操作する

ウォッチフェイスプッシュを扱う際の重要なコンセプトは、スロットです。スロットは、アプリに属するインストール済みのウォッチフェイスをアドレス指定する方法です。システムは、マーケットプレイスが持つことができるスロットの最大数を設定します。Wear OS 6 では、上限は 1 です。

ウォッチフェイスを更新または削除する際に、slotId は、操作対象のウォッチフェイスを特定するために使用されます。

ウォッチフェイスを一覧表示する

インストールされているウォッチフェイスのセットを一覧表示するには、listWatchFaces() を使用します。

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")WatchFacePush.kt

これにより、スロットが使用可能かどうか、別のウォッチフェイスを追加するには既存のウォッチフェイスを置き換える必要があるかどうかを判断できます。このリストには、インストールされているウォッチフェイスの詳細も表示されます。たとえば、特定のウォッチフェイスパッケージがインストールされているかどうかを確認するには:

suspend fun isInstalled(packageName: String) = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }WatchFacePush.kt

ウォッチフェイスを追加する

listWatchFaces レスポンスでスロットが利用可能と判断された場合は、addWatchFace() メソッドを使用する必要があります。

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}WatchFacePush.kt

ウォッチフェイスを更新する

ウォッチフェイスを更新すると、指定したスロットの内容を新しいパッケージに置き換えることができます。同じウォッチフェイスを新しいバージョンにアップグレードするか、ウォッチフェイスを別のものに完全に置き換えることができます。

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}WatchFacePush.kt

ウォッチフェイスを削除する

文字盤を削除するには:

// Remove the com.example.watchfacepush.green watch face.
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}WatchFacePush.kt

この方法では、ウォッチフェイスは常にシステムのウォッチフェイス選択ツールに表示されます。ロゴを大きく表示したり、スマートフォンで Marketplace アプリを起動するボタンを表示したりすることもできます。

ウォッチフェイスが有効になっているかどうかを確認する

マーケットプレイスでアクティブなウォッチフェイスが設定されているかどうかを判断することは、ユーザーがスムーズに操作できるようにするために重要です。マーケットプレイスですでにアクティブなウォッチフェイスが設定されている場合、ユーザーが別のウォッチフェイスを選択するには、マーケットプレイスアプリで現在のウォッチフェイスを置き換えるだけで済みます。ただし、マーケットプレイスにアクティブなウォッチフェイスが設定されていない場合は、スマートフォンアプリでユーザーに詳細なガイダンスを提供する必要があります。このユーザーエクスペリエンスの処理方法について詳しくは、電話アプリに関するセクションをご覧ください。

マーケットプレイスでアクティブなウォッチフェイスが設定されているかどうかを確認するには、次のロジックを使用します。

suspend fun hasActiveWatchFace() = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }WatchFacePush.kt

デフォルトのウォッチフェイスを提供する

ウォッチフェイスプッシュを使用すると、マーケットプレイスアプリのインストール時にデフォルトのウォッチフェイスをインストールできます。これだけでは、そのデフォルトのウォッチフェイスがアクティブに設定されるわけではありません（アクティブなウォッチフェイスの設定を参照）。ただし、システムウォッチフェイス選択ツールでウォッチフェイスが利用できるようになります。

この機能を使用するには:

Wear OS アプリのビルドで、デフォルトのウォッチフェイスをパスに含めます。 assets/default_watchface.apk

AndroidManifest.xml に次のエントリを追加します。

<meta-data
    android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
    android:value="@string/default_wf_token" />AndroidManifest.xml

アクティブなウォッチフェイスを設定する

ウォッチフェイスプッシュは、マーケットプレイスアプリがアクティブなウォッチフェイスを設定する手段を提供します。

具体的には、現在のアクティブなウォッチフェイスがマーケットプレイスに属していない場合、アプリはアクティブなウォッチフェイスをマーケットプレイスに属するものに設定できます。マーケットプレイスにアクティブなウォッチフェイスがすでに存在する場合、別のウォッチフェイスに変更するには、updateWatchFace を呼び出して、ウォッチフェイススロットの内容を別のウォッチフェイスに置き換えます。

アクティブなウォッチフェイスを設定するプロセスは 2 段階です。

アクティブなウォッチフェイスの設定に必要な Android の権限を取得します。
setWatchFaceAsActive メソッドを呼び出します。

アクティブなウォッチフェイスを設定する権限を取得する

必要な権限は SET_PUSHED_WATCH_FACE_AS_ACTIVE です。これはマニフェストに追加する必要があります。

<!-- Required to be able to call the setWatchFaceAsActive() method. -->
<uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />AndroidManifest.xml

これはランタイム権限であるため、アプリの実行時にユーザーにこの権限をリクエストする必要があります（この処理を支援する Accompanist ライブラリの使用を検討してください）。

ウォッチフェイスをアクティブに設定する

権限が付与されたら、アクティブにするウォッチフェイスのスロット ID で setWatchFaceAsActive を呼び出します。

この手段が使用されたら、スマートフォンアプリは、アクティブなウォッチフェイスを手動で設定する方法に関するガイダンスを提供するようにします。

ウォッチフェイス APK から追加のメタデータを読み取る

WatchFaceSlot オブジェクトは、ウォッチフェイスで宣言できる追加情報を取得する手段も提供します。

これは、同じ文字盤のマイナーバリエーションがある場合に特に便利です。たとえば、次のようにウォッチフェイスを定義できます。

Package name: com.myapp.watchfacepush.mywatchface
パッケージバージョン: 1.0.0

ただし、この文字盤は 4 つの異なる APK として提供される可能性があります。これらの APK はほぼ同じですが、デフォルトの色が異なります。Watch Face Format XML の ColorConfiguration で、赤、黄、緑と青が設定されています。

このわずかなバリエーションは、次の 4 つの APK に反映されます。

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
    android:name="default_color"
    android:value="red" />AndroidManifest.xml

カスタムプロパティを使用すると、アプリでこれらのバリエーションのどれがインストールされているかを判断できます。

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")WatchFacePush.kt

考慮事項

アプリでウォッチフェイスプッシュを実装する際の重要な考慮事項には、消費電力、キャッシュ保存、バンドルされたウォッチフェイスの更新、代表的なデフォルトのウォッチフェイスの提供などがあります。

電源

Wear OS で動作するアプリの重要な考慮事項は、消費電力です。マーケットプレイスアプリの Wear OS コンポーネントの場合:

アプリは、可能な限り実行頻度を低く、実行時間を短くする必要があります（ユーザーが直接操作している場合を除く）。これには、次が含まれます。
- 電話アプリからアプリを起動する回数を最小限に抑える
- WorkManager ジョブの実行を最小限に抑える
スマートウォッチの充電中にアナリティクスレポートのスケジュールを設定する:
1. Wear OS アプリの使用状況統計情報やその他の指標をレポートする場合は、requiresCharging 制約を使用して WorkManager を使用します。
スマートウォッチの充電中に Wi-Fi を利用して更新をスケジュール設定する:
1. インストールされているウォッチフェイスのバージョンを確認し、自動的に更新することもできます。ここでも、requiresNetworkType に requiresCharging 制約と UNMETERED ネットワークタイプを使用します。
2. 充電中は、デバイスが Wi-Fi にアクセスできる可能性が高くなります。Wi-Fi をリクエストして更新された APK をすばやくダウンロードし、完了したらネットワークを解放します。
3. このガイダンスは、マーケットプレイスで今日のウォッチフェイスが提供される場合にも適用されます。スマートウォッチの充電中にダウンロードしておきましょう。
アクティブなウォッチフェイスを確認するジョブをスケジュールしない:
1. マーケットプレイスにアクティブなウォッチフェイスがまだあるかどうか、また、どのウォッチフェイスがアクティブであるかを定期的に確認すると、バッテリーが消耗します。この方法は避けてください。
スマートウォッチで通知を使用しない:
1. アプリで通知を使用している場合は、スマートフォンに通知を集中させます。ユーザーが操作すると、スマートフォンアプリが開いてジャーニーが継続されます。setLocalOnly を使用して、通知がスマートウォッチアプリにブリッジされないように構成します。

キャッシュ

標準的なマーケットプレイスの例では、ウォッチフェイスはスマートフォンからスマートウォッチに転送されます。この接続は通常 Bluetooth 接続であり、かなり遅くなる可能性があります。

ユーザーエクスペリエンスを向上させ、再送信電力を節約するため、Wear OS デバイスに少数の APK を保存する小さなキャッシュを実装することを検討してください。

別の文字盤を試した後に、以前選択した文字盤に戻すことにした場合は、この操作はほぼ瞬時に行われます。

同様に、Wear OS デバイスの充電中にウォッチフェイスがダウンロードされる、今日のウォッチフェイスなどのスキームのプリキャッシュにも使用できます。

バンドルされているウォッチフェイスを更新する

アプリには、前述のとおり、デフォルトのウォッチフェイスアセットを含めることができます。この文字盤は、マーケットプレイスアプリのインストール時にシステムにインストールされますが、マーケットプレイスアプリのアップデートに新しいバージョンがバンドルされても、文字盤はアップデートされないことに注意してください。

この状況に対処するには、マーケットプレイスアプリで MY_PACKAGE_REPLACED ブロードキャストアクションをリッスンし、パッケージアセットからバンドルされたウォッチフェイスを更新する必要があるかどうかを確認する必要があります。

代表的なデフォルトのウォッチフェイス

デフォルトのウォッチフェイスは、ユーザーがマーケットプレイスを見つけて利用するうえで非常に役立ちます。ウォッチフェイスはマーケットプレイスのインストール時にインストールされるため、ユーザーはウォッチフェイスギャラリーでウォッチフェイスを見つけることができます。

デフォルトのウォッチフェイスを使用する際の考慮事項は次のとおりです。

ユーザーがマーケットプレイスアプリからウォッチフェイスをアンインストールすることを選択した場合は、removeWatchFace を使用しないでください。代わりに、この場合は updateWatchFace を使用してウォッチフェイスをデフォルトのウォッチフェイスに戻します。これにより、ユーザーはギャラリーからウォッチフェイスを見つけて設定できます。
ロゴとテーマ設定により、デフォルトのウォッチフェイスをシンプルで一目でわかるものにします。これにより、ユーザーはウォッチフェイスギャラリーでこのウォッチフェイスを見つけやすくなります。
デフォルトの文字盤にスマートフォンアプリを開くボタンを追加します。これは 2 つの段階で実現できます。
1. ウォッチフェイスに Launch 要素を追加して、Wear OS アプリを使用してインテントを起動します。例:
  
  <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />
2. LaunchOnPhoneActivity で、RemoteActivityHelper を使用して電話アプリを起動します。