本頁面由 Cloud Translation API 翻譯而成。

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

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

設定

加入必要的依附元件：

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 可存取所有與錶面推送互動的方法。

使用運算單元

使用錶面推送功能時，版位是重要概念。應用程式安裝的錶面會使用「時段」來處理。系統會為市集設定運算單元數量上限；在 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" />

設定使用中的錶面

透過錶面推送功能，市集應用程式可以設定使用中的錶面。

具體來說，如果目前使用的錶面不屬於 Marketplace，應用程式可以將 Marketplace 的錶面設為使用中錶面。請注意，如果市集已提供使用中的錶面，則可透過呼叫 updateWatchFace 將錶面插槽的內容替換為其他錶面，藉此變更錶面。

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

取得設定使用中錶面所需的 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 程式庫協助處理)。

將錶面設為使用中

授予權限後，請在應啟用的錶面 slot 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 元件：

應用程式應盡可能減少執行次數和頻率 (除非使用者直接與應用程式互動)。包括：
- 盡量減少從手機應用程式喚醒應用程式的情況
- 盡量減少 WorkManager 工作執行次數
安排在手錶充電時產生數據分析報表：
1. 如要回報 Wear OS 應用程式或其他指標的使用統計資料，請使用 WorkManager 和 requiresCharging 限制。
在手錶充電時透過 Wi-Fi 安排更新：
1. 建議你檢查已安裝的錶面版本，並自動更新。同樣地，請使用 requiresCharging 限制和 UNMETERED 網路類型做為 requiresNetworkType。
2. 充電時，裝置通常可以連上 Wi-Fi。要求使用 Wi-Fi 快速下載更新版 APK，完成後釋放網路。
3. 如果市集提供每日錶面，也請按照上述做法操作，在手錶充電時預先下載。
請勿排定作業來檢查有效錶面：
1. 定期檢查市集是否仍有有效的錶面，以及是哪個錶面，會消耗電池電量。請避免使用這種方法。
不要在手錶上使用通知：
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 啟動電話應用程式。