設定 Wear OS 應用程式以便使用錶面推播功能

透過 Watch Face Push，應用程式可管理 Wear OS 裝置上的錶面。包括新增、更新和移除錶面，以及設定使用中錶面。設定 Wear OS 應用程式，以便使用 Watch Face Push API。

設定

加入必要的依附元件：

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.
}

這樣一來，系統錶面挑選器就能隨時找到您的錶面，並以醒目方式顯示您的標誌，甚至還能提供按鈕，讓使用者在手機上啟動您的 Marketplace 應用程式。

確認錶面是否處於啟用狀態

為了確保使用者享有順暢的體驗，請務必判斷市集是否已設有有效的錶面：如果市集已設有有效的錶面，當使用者想要選擇其他錶面時，只需透過市集應用程式替換目前的錶面即可生效。不過，如果市集沒有提供有效錶面，手機應用程式必須提供更多指引給使用者。如要進一步瞭解如何處理這項使用者體驗，請參閱「電話應用程式」一節。

如要判斷市集是否已設定使用中的錶面，請按照下列步驟操作：

提供預設錶面

錶面推播功能可在安裝市集應用程式時安裝預設錶面。這項操作本身不會將預設錶面設為使用中 (請參閱設定使用中錶面)，但會確保系統錶面挑選器中可使用您的錶面。

如何使用這項功能：

  1. 在 Wear OS 應用程式版本中，將預設錶面納入路徑：assets/default_watchface.apk

  2. 將下列項目新增至 AndroidManifest.xml

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

設定使用中的錶面

錶面推播可讓市集應用程式設定使用中的錶面。

也就是說，如果目前的使用中錶面不屬於市集，應用程式可以將使用中錶面設為屬於市集的錶面。請注意，如果市集已提供使用中的錶面，您可以透過呼叫 updateWatchFace 將錶面版位的內容替換為其他錶面，藉此變更錶面。

設定使用中的錶面有兩個階段：

  1. 取得設定使用中錶面所需的 Android 權限。
  2. 呼叫 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

但這個錶面可能會以四個不同的 APK 提供，其中所有 APK 幾乎完全相同，但預設顏色不同：紅色、黃色、綠色和藍色，這些顏色會在錶面格式 XML 的 ColorConfiguration 中設定。

這項微小變化會反映在四個 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 元件：

  1. 應用程式應盡可能減少執行次數，並盡可能減少執行頻率 (除非使用者直接與其互動)。包括：
    • 盡量避免從「電話」應用程式喚醒應用程式
    • 盡量減少 WorkManager 工作執行次數
  2. 安排任何數據分析報表，以便在手錶充電時執行：
    1. 如果您想回報 Wear OS 應用程式或任何其他指標的使用統計資料，請使用含有 requiresCharging 限制的 WorkManager。
  3. 在手錶充電時安排更新，並使用 Wi-Fi：
    1. 建議您檢查已安裝的錶面版本，並自動更新。再次使用 requiresCharging 限制條件，並為 requiresNetworkType 使用 UNMETERED 網路類型。
    2. 充電時，裝置可能會連上 Wi-Fi。要求使用 Wi-Fi 快速下載更新版 APK，並在完成後釋放網路。
    3. 市集可能會提供每日錶面，因此建議在錶款充電時預先下載。
  4. 請勿排定檢查目前錶面的作法：
    1. 定期檢查市集是否仍有有效的錶面，以及哪個錶面會耗用電池。請避免採用這種做法。
  5. 不要在手錶上使用通知：
    1. 如果應用程式使用通知，請將通知顯示在手機上，讓使用者透過開啟手機應用程式繼續流程。請確認這些項目不會使用 setLocalOnly 連結至智慧手錶應用程式。

快取

在標準市集範例中，錶面會從手機傳輸到手錶。這類連線通常是藍牙連線，速度可能相當緩慢。

為了提供更好的使用者體驗，並節省重傳功率，建議您在 Wear OS 裝置中實作小型快取，用於儲存少量 APK。

如果使用者嘗試其他錶面，但決定恢復先前選擇的錶面，這項操作幾乎是即時完成。

同樣地，這項功能也可用於為每日錶面或類似的方案進行預快取，在 Wear OS 裝置充電時下載錶面。

更新套件內的錶面

您的應用程式可能會包含預設錶面素材資源，如前文所述。請注意，雖然安裝市集應用程式時，系統會安裝這個錶面，但如果市集應用程式更新時隨附較新版本，錶面不會更新。

為處理這種情況，市集應用程式應監聽 MY_PACKAGE_REPLACED 廣播動作，並檢查是否需要從套件資產更新任何內含的錶面。

代表性的預設錶面

預設錶面是協助使用者發現及使用市集的絕佳方式：錶面會在市集安裝時安裝，因此使用者可以在錶面相片庫中找到錶面。

使用預設錶面時，請考量以下幾點：

  • 如果使用者選擇從市集應用程式中解除安裝錶面，請勿使用 removeWatchFace。在這種情況下，請改用 updateWatchFace 將錶面還原為預設錶面。這有助於使用者在相片庫中找到您的錶面並進行設定。
  • 透過標誌和主題設定，讓預設錶面簡單易懂，一眼就能辨識。這有助於使用者在錶面相片庫中找到錶面。

  • 在預設錶面中新增按鈕，以便開啟電話應用程式。這可分兩個階段完成：

    1. 在錶面中新增 Launch 元素，即可使用 Wear OS 應用程式啟動意圖，例如：

      <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

    2. 在 LaunchOnPhoneActivity 中，使用 RemoteActivityHelper 啟動電話應用程式。