このページは Cloud Translation API によって翻訳されました。

ウォッチフェイスプッシュ用に Wear OS アプリを構成する
コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

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

設定

必要な依存関係を含めます。

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

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

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

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

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

</manifest>

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

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

val manager = WatchFacePushManager(context)

WatchFacePushManager は、ウォッチフェイスプッシュを操作するためのすべてのメソッドにアクセスできます。

スロットを操作する

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

ウォッチフェイスを更新または削除する場合、slotId を使用して、操作を行うウォッチフェイスを識別します。

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

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

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

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

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

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

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: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

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

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

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

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

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

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

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

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

これにより、ウォッチフェイスがシステムのウォッチフェイス選択ツールで常に表示され、ロゴを目立つように表示したり、スマートフォンでマーケットプレイスアプリを起動するボタンを表示したりできます。

ウォッチフェイスがアクティブかどうかを確認する

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

マーケットプレイスでアクティブなウォッチフェイスが設定されているかどうかを確認するには:

デフォルトのウォッチフェイスを指定する

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

この機能を使用するための要件は次のとおりです。

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

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

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

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

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

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

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

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

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

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

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

watchFacePushManager.setWatchFaceAsActive(slotId)

この方法を使用した後は、スマートフォンアプリで、アクティブなウォッチフェイスを手動で設定する方法についてのガイダンスが表示されます。

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

WatchFaceSlot オブジェクトには、ウォッチフェイスで宣言できる追加情報を取得する手段も用意されています。

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

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

ただし、このウォッチフェイスは 4 つの異なる APK として提供される場合があります。これらはすべてほぼ同じですが、デフォルトの色が異なります（赤、黄、緑、青）。デフォルトの色は、Watch Face Format XML の ColorConfiguration で設定します。

このわずかな差異が、4 つの APK のそれぞれに反映されます。

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

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

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

考慮事項

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

電源

Wear OS で実行されるアプリでは、消費電力に注意する必要があります。ショッピングモールアプリの Wear OS コンポーネントの場合:

アプリは、ユーザーが直接操作する場合を除き、できるだけ少なく、頻繁に実行しないでください。これには、次のものが含まれます。
- 電話アプリからアプリを起動することを最小限に抑える
- WorkManager ジョブの実行を最小限に抑える
アナリティクスレポートのスケジュールをスマートウォッチの充電時に設定する:
1. Wear OS アプリまたはその他の指標の使用状況統計情報を報告する場合は、requiresCharging 制約を使用して WorkManager を使用します。
スマートウォッチが充電され、Wi-Fi が利用されているときに更新をスケジュールする:
1. インストールされているウォッチフェイスのバージョンを確認し、自動的に更新することもできます。ここでも、requiresCharging 制約と UNMETERED ネットワークタイプを requiresNetworkType に使用します。
2. 充電中は、デバイスが Wi-Fi に接続されている可能性が高いです。更新された APK をWi-Fi で迅速にダウンロードし、完了したらネットワークを解放します。
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 を使用して電話アプリを起動します。