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

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

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

設定

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

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

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 = WatchFacePushManagerFactory.createWatchFacePushManager(context)

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

スロットを操作する

ウォッチフェイスプッシュを扱う際の重要なコンセプトは、スロットです。スロットは、アプリに属するインストール済みのウォッチフェイスをアドレス指定する方法です。システムは、マーケットプレイスが持つことができるスロットの最大数を設定します。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.
}

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

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

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

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

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

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

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

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

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

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

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

具体的には、現在アクティブなウォッチフェイスがマーケットプレイスに属していない場合、アプリはアクティブなウォッチフェイスをマーケットプレイスに属するものに設定できます。マーケットプレイスにアクティブなウォッチフェイスがすでに存在する場合、別のウォッチフェイスに変更するには、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 として提供される可能性があります。これらの 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. インストールされているウォッチフェイスのバージョンを確認し、自動的に更新することもできます。ここでも、requiresNetworkType に requiresCharging 制約と UNMETERED ネットワークタイプを使用します。
2. 充電中は、デバイスが Wi-Fi にアクセスできる可能性が高くなります。Wi-Fi をリクエストして更新された APK をすばやくダウンロードし、完了したらネットワークを解放します。
3. このガイダンスは、マーケットプレイスで今日のウォッチフェイスが提供される場合にも適用されます。スマートウォッチの充電中に、これを事前にダウンロードしてください。
アクティブなウォッチフェイスを確認するジョブをスケジュール設定しないでください:
1. マーケットプレイスにアクティブなウォッチフェイスがまだあるかどうか、また、どのウォッチフェイスであるかを定期的に確認すると、バッテリーが消耗します。この方法は避けてください。
スマートウォッチで通知を使用しない:
1. アプリで通知を使用している場合は、スマートフォンに通知を集中させます。ユーザーが操作すると、スマートフォンアプリが開いてジャーニーが継続されます。setLocalOnly を使用して、これらがウォッチアプリにブリッジされないようにします。

キャッシュ

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

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

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

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

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

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

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

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

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

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

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