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

借助表盘推送功能，您的应用可以管理 Wear OS 设备上的表盘。这包括添加、更新和移除表盘主题，以及设置当前表盘主题。将 Wear OS 应用配置为使用表盘推送 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 提供对所有用于与表盘推送功能交互的方法的访问权限。

使用槽

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

更新表盘

更新表盘主题可让您使用新软件包替换指定 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

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

提供默认表盘

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

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

1. 在 Wear OS 应用 build 中，将默认表盘包含在以下路径中：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" />
   

设置当前表盘主题

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

具体而言，这意味着，如果当前有效表盘不属于 Marketplace，应用可以将有效表盘设置为属于 Marketplace 的表盘。请注意，如果应用商店中已包含当前表盘，则通过调用 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 库来帮助完成此操作）。

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

授予权限后，对应该处于活动状态的表盘的 slot ID 调用 setWatchFaceAsActive：

watchFacePushManager.setWatchFaceAsActive(slotId)

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

从表盘 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" />

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

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

注意事项

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

电源

对于在 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 启动电话应用。