此页面由 Cloud Translation API 翻译。

表盘推送

Wear OS 6 引入了新的 API，即表盘推送，为实现更高级的表盘发布用例提供了机会。

确定何时使用表盘推送

Watch Face Push 是 Wear OS 上的一项 API，可让开发者直接添加、更新或移除表盘。标准表盘开发不需要它。

与表盘推送功能搭配使用的表盘必须使用表盘格式编写。这可能包括使用 Watch Face Studio 或任何其他使用表盘格式生成表盘的工具设计的表盘。

虽然 Watch Face Push API 可能有多种用法，但您应将下表作为主要用例的指南：

用例	推荐解决方案	复杂性
我想创建个性化表盘主题并发布它们。	直接或通过 Watch Face Studio 等工具使用表盘格式，并在 Google Play 上发布表盘主题。	低
我想创建一个手机应用，让用户能够从精选集合中选择表盘，或设计和自定义表盘，以便直接安装到 Wear OS 手表上。	在手表上使用表盘推送 API 创建适用于手表和手机的应用。	高

用途

Watch Face Push API 的典型用例是创建购物平台应用。通过此应用，用户可以从手机上的精选合集中选择表盘，并直接控制将这些表盘安装到已连接的手表上。

注意事项

如需详细了解如何构建表盘，请参阅表盘格式指南：使用表盘推送功能部署的表盘是常规表盘格式表盘。

在构建表盘时，请注意以下注意事项。

软件包名称

使用表盘推送功能安装的表盘必须遵循以下惯例：

<app name>.watchfacepush.<watchface name>

... 其中 <app name> 是调用表盘推送 API 的应用的软件包名称。

例如，对于软件包名称为 com.example.mymarketplace 的应用，以下是有效的表盘软件包名称：

com.example.mymarketplace.watchfacepush.watchface1
com.example.mymarketplace.watchfacepush.watchface2
com.example.mymarketplace.watchfacepush.another_watchface

API 会拒绝不符合此惯例的表盘主题。

软件包内容

我们会严格执行 APK 内容政策。您需要小心确保表盘格式符合以下约束条件：从技术上讲，您可以生成包含无害元数据文件和其他工件的表盘格式 APK，这些 APK 可能符合 Google Play 的要求，但无法通过表盘推送验证（见下文）。

每个表盘 APK 中只能包含以下文件/路径：

/AndroidManifest.xml
/resources.arsc
/res/**
/META-INF/**

此外，AndroidManifest.xml 文件中仅允许使用以下标记：

<manifest>
<uses-feature>
<uses-sdk>
<application>
<property>
<meta-data>

最后，软件包应指定至少为 33 的 minSdk，并且 <application> 标记应指定属性 android:hasCode="false"。

验证

与通过 Google Play 分发的常规表盘不同，Marketplace 应用负责执行表盘推送检查，以确保每个表盘都采用良好的格式且性能出色。

Google Play 会使用以下验证检查来验证使用表盘推送功能的每个表盘的质量：

通过表盘推送 API 安装或更新的所有表盘都必须通过表盘推送验证工具的验证。
只有官方验证工具才能用于生成验证令牌，以便与该 API 搭配使用。
运行验证时，使用的验证工具必须是最新版本。
无需重新验证未发生更改的 APK。令牌不会过期，即使所用验证工具的版本已被取代也是如此。

同时，我们建议您每隔一段时间重新运行一次验证，因为验证程序会定期更新。

运行验证工具

验证器既可作为 CLI 工具使用，也可作为库使用。

命令行验证器的使用

从 Google 的 Maven 制品库中获取验证器。
运行该工具，如下所示：
```
java -jar validator-push-cli-1.0.0-alpha03.jar \
    --apk_path=<your watch face>.apk \
    --package_name=<your marketplace package name>
```
如果成功，输出中会包含一个验证令牌，您必须在添加或更新表盘时将其提供给表盘推送 API。

如果发生错误，输出中会包含有关哪项具体检查失败的详细信息。

库验证器使用

添加 Jitpack 代码库，该代码库是验证器依赖项所必需的：

repositories {
    ...
    maven {
        url = uri("https://jitpack.io")
        content {
            includeGroup("com.github.xgouchet")
        }
    }
}

在项目中添加验证器依赖项：

// Check for the latest version
implementation("com.google.android.wearable.watchface.validator:1.0.0-alpha03")

运行验证工具：

val validator = DwfValidatorFactory.create()
val result = validator.validate(watchFaceFile, appPackageName)

if (result.failures().isEmpty()) {
    val token = result.validationToken()
    println("Validation token: $token")

    // Validation success - continue with the token
    // ...
} else {
    // There were failures, handle them accordingly - validation has failed.
    result.failures().forEach { failure ->
        println("FAILURE: ${failure.name()}: ${failure.failureMessage()}")
        // ...
    }
}Main.kt

如需查看使用此库的示例，请参阅 GitHub 示例。

APK 大小

请特别注意表盘推送表盘，以确保 APK 大小尽可能小：表盘 APK 可能会通过蓝牙从手机应用传输到手表应用，而传输速度可能会很慢。

APK 过大可能会需要很长时间才能传输完毕，这会导致用户体验不佳，并耗费电池电量。

使用适当的库（例如 pngquant）将图片文件大小降至最低
- 将其添加到表盘合集构建流程中
- 检查图片的尺寸是否适合其将要使用的放大比例。
- 确保图片经过适当剪裁，以移除所有周围背景。
缩减字体文件的大小
- 例如，如果您仅使用特定字体来显示格式为 HH:MM 的时间，则可以使用 pyftsubset 等工具限制字体文件仅包含必要的字形。这可以显著缩减生成的字体文件和 APK 的大小。如需了解如何在其他情况下尽可能缩减字体文件大小，请参阅这篇博文。

如需有关尽可能缩减 APK 大小的进一步建议，请参阅优化内存用量指南。

APK 签名

与常规 APK 一样，您的所有表盘都需要签名。创建与主要应用使用的密钥不同的密钥，并为所有表盘使用该密钥。

架构

我们来看看该系统的三个主要组件：

基于云的存储：在规范的 Marketplace 应用中，您的表盘会在云端构建并存储，以供用户使用。表盘主题如下：
1. 预构建为常规表盘格式 APK
2. 每个文件夹中仅包含一个基于表盘格式的表盘
3. 已使用表盘推送验证流程通过验证，并与关联的验证令牌一起存储。
4. 随时可供手机应用检索。
电话应用：电话应用是用户与系统互动的主要方式。借助此功能，他们可以：
1. 浏览和搜索表盘目录
2. 在手表上安装或更换表盘
手表应用：手表应用通常没有明显的界面。它主要充当手机应用和表盘推送 API 之间的桥梁，具有以下功能：
1. 使用 Watch Face Push API 安装/更新或替换表盘
2. 请求必要权限并提示用户
3. 提供默认表盘
4. 提供最少的表盘缓存
手机与手表之间的通信：手机与手表应用之间的通信对于整体体验的成功至关重要。使用 Wear OS 数据层 API，这些 API 支持：
1. 安装检测：使用 capability 和 CapabilityClient，手机应用可以检测手表应用是否缺失，反之亦然。然后，可以向 Play 商店发起 intent 以安装缺少的设备规格。
2. 状态管理：使用 DataClient 或 MessageClient，可让手机与手表的状态保持同步，例如确保手机知道已设置的表盘。
3. APK 传输：使用 ChannelClient 或 MessageClient，可以将 APK 从手机发送到手表
4. 远程调用：使用 Messageclient，手机可以指示手表调用表盘推送 API，例如安装表盘。

如需了解详情，请参阅 Data Layer API 指南。