配置 Wear OS 应用以实现表盘推送

借助表盘推送功能，您的应用可以管理 Wear OS 设备上的表盘。这包括添加、更新和移除表盘主题，以及设置当前表盘主题。将 Wear OS 应用配置为使用 Watch Face Push API。

设置

在 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 提供对所有用于与表盘推送功能互动的相关方法的访问权限。

使用槽

使用表盘推送功能时，一个关键概念是“slot”（插槽）。slot 是一种用于寻址属于您的应用的已安装表盘的方式。系统会设置一个应用商店可拥有的插槽数量上限；在 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

添加表盘主题

如果存在可用 slot（由 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

更新表盘

更新表盘主题可让您使用新软件包替换指定 slot 的内容。这可能是将同一表盘升级到较新版本，也可能是完全替换为其他表盘。

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

这种方法意味着，您的表盘始终可以在系统表盘选择器中找到。您可以醒目地展示徽标，甚至可以展示一个按钮，以便在手机上启动您的 G Suite 应用商店应用。

检查表盘是否处于有效状态

确定您的应用商店是否已设置有效表盘对于帮助用户获得顺畅的体验至关重要：如果应用商店已设置有效表盘，那么当用户想要选择其他表盘时，只需通过应用商店应用替换当前表盘即可生效。不过，如果应用商店中没有设置有效的表盘主题，手机应用必须为用户提供更多指导。如需详细了解如何处理此用户体验，请参阅有关手机应用的部分。

如需确定应用商店是否已设置活跃表盘，请使用以下逻辑：

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

提供默认表盘

借助表盘主题推送功能，您可以在安装应用商店应用时安装默认表盘主题。这本身并不会将该默认表盘设为当前表盘（请参阅设置当前表盘），但会让您的表盘在系统表盘选择器中可用。

若要使用该功能，请执行以下操作：

1. 在 Wear OS 应用 build 中，将默认表盘包含在路径中： assets/default_watchface.apk

2. 将以下条目添加到 AndroidManifest.xml

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

设置当前表盘主题

表盘推送功能可让应用商店应用设置当前表盘。

具体而言，这意味着，如果当前有效表盘不属于 Marketplace，应用可以将有效表盘设置为属于 Marketplace 的表盘。请注意，如果应用商店中已包含当前表盘，则通过调用 updateWatchFace 将表盘插槽的内容替换为另一个表盘，即可将当前表盘更改为另一个表盘。

设置当前表盘主题分为两个阶段：

1. 获取设置有效表盘所需的 Android 权限。
2. 调用 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 库来帮助完成此操作）。

将表盘主题设为当前表盘主题

授予权限后，在应处于活动状态的表盘的 slot ID 上调用 setWatchFaceAsActive。

使用此方法后，手机应用应改为提供有关如何手动设置有效表盘的指导。

从表盘 APK 中读取其他元数据

WatchFaceSlot 对象还提供了一种获取可在表盘上声明的其他信息的方法。

这在您有同一表盘的次要变体时尤其有用。例如，您可以定义一个表盘：

• 软件包名称：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" />
AndroidManifest.xml

使用自定义属性可让您的应用确定安装的是哪个变体：

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

注意事项

在应用中实现表盘推送功能时，需要重点考虑的事项包括功耗、缓存、更新随附的表盘以及提供具有代表性的默认表盘。

电源

对于在 Wear OS 上运行的任何应用，耗电量都是一项关键考虑因素。对于 Marketplace 应用的 Wear OS 组件：

1. 您的应用应尽可能少地运行，并且运行频率尽可能低（除非用户直接与应用互动）。其中包括：
   • 最大限度地减少从手机应用唤醒应用
   • 最大限度减少 WorkManager 作业的运行
2. 安排在手表充电时生成任何分析报告：
   1. 如果您想报告 Wear OS 应用的使用情况统计信息或任何其他指标，请使用带有 requiresCharging 限制条件的 WorkManager。
3. 安排在手表充电并使用 WLAN 时更新：
   1. 您可能需要检查已安装的表盘主题的版本，并自动更新它们。同样，请对 requiresNetworkType 使用 requiresCharging 限制和 UNMETERED 网络类型。
   2. 充电时，设备很可能可以访问 Wi-Fi。请求 Wi-Fi 以快速下载更新后的 APK，并在完成后释放网络。
   3. 如果市场提供每日表盘主题，则同样适用此指南；在手表充电时预先下载。
4. 不安排作业来检查活跃的表盘：
   1. 定期检查您的应用商店是否仍有有效的表盘主题以及是哪个表盘主题会消耗电池电量。请避免采用这种方法。
5. 不在手表上使用通知：
   1. 如果您的应用使用通知，请将这些通知重点放在手机上，以便用户通过操作打开手机应用来继续体验历程。使用 setLocalOnly 配置通知，使其不会桥接到手表应用。

缓存

在规范的市场示例中，表盘主题是从手机转移到手表的。此连接通常是蓝牙连接，速度可能相当慢。

为了提供更好的用户体验并节省重传功率，请考虑在 Wear OS 设备中实现一个小型缓存，用于存储少量 APK。

如果用户尝试了其他表盘，但随后决定恢复为之前选择的表盘，则此操作几乎是即时完成的。

同样，这也可用于预缓存每日表盘或类似方案，在 Wear OS 设备充电时下载表盘。

更新捆绑的表盘

您的应用可以包含如前所述的默认表盘主题资源。请务必注意，虽然此表盘会在安装应用商店应用时安装到系统中，但如果应用商店应用的任何更新中包含更新版本的表盘，该表盘也不会更新。

为处理这种情况，您的应用商店应用应监听 MY_PACKAGE_REPLACED 广播操作，并检查是否需要更新任何来自软件包资源中的捆绑式表盘。

代表性的默认表盘

默认表盘主题可帮助用户发现并使用您的应用商店：当您的应用商店安装完毕后，系统也会安装该表盘主题，因此用户可以在表盘主题库中找到它。

使用默认表盘时的一些注意事项：

• 如果用户选择从您的 Marketplace 应用中卸载表盘，请勿使用 removeWatchFace。在这种情况下，请使用 updateWatchFace 将表盘恢复为默认表盘。这有助于用户在图库中找到您的表盘并进行设置。
• 通过徽标和主题，让默认表盘简单且可立即识别。这有助于用户在表盘库中找到该表盘。

• 向默认表盘添加一个按钮，用于打开“电话”应用。这可以通过两个阶段来实现：

  1. 向表盘添加 Launch 元素，以使用 Wear OS 应用启动 intent，例如：

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

  2. 在 LaunchOnPhoneActivity 中，使用 RemoteActivityHelper 启动电话应用。