表盘推送

Wear OS 6 引入了一项新的 API，即表盘推送，这为更高级的表盘发布用例创造了机会。

确定何时使用表盘推送

表盘推送是 Wear OS 上的一个 API，可让开发者直接添加、更新或移除表盘。标准表盘开发不需要此权限。

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

虽然表盘推送 API 可以有多种潜在用途，但下表应作为主要使用情形的指南：

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

用途

表盘推送 API 的典型使用情形是创建 Marketplace 应用。通过此应用，用户可以在手机上从精选的表盘主题集中选择表盘主题，并直接控制将这些表盘主题安装到已连接的手表上。

注意事项

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

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

软件包名称

使用表盘推送安装的表盘必须符合以下惯例：

<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 分发的常规表盘不同，Watch Face Push 会检查以确保每个表盘都具有良好的格式和性能，而这是 Marketplace 应用的责任。

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

  1. 通过表盘推送 API 安装或更新的所有表盘都必须通过表盘推送验证工具。
  2. 只有官方验证工具可用于生成与 API 搭配使用的验证令牌。
  3. 所使用的验证工具在运行验证时必须是最新的。

  4. 如果 APK 没有更改，则无需重新验证。即使所用验证工具的版本被取代，令牌也不会过期。

    与此同时，我们建议您不时重新运行验证器，因为验证器会定期更新。

运行验证器

验证器有三种形式：

  • CLI 工具
  • 适用于 JVM 的库
  • 可在 Android 上使用的库

命令行验证器的用法

  1. 从 Google 的 Maven 制品库获取验证器。

  2. 运行该工具，如下所示：

    java -jar validator-push-cli-1.0.0-alpha06.jar \
    --apk_path=<your watch face>.apk \
    --package_name=<your marketplace package name>

    如果成功，输出会包含一个验证令牌，您在添加或更新表盘时必须将此令牌提供给表盘推送 API。

    如果发生错误，输出会包含有关哪个特定检查失败的详细信息。

库验证器使用情况

  1. 添加验证器依赖项所需的 Jitpack 代码库：

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

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

    // For use on JVM
implementation("com.google.android.wearable.watchface.validator:1.0.0-alpha06")

// For use on Android
implementation("com.google.android.wearable.watchface.validator-android:1.0.0-alpha06")

  3. 运行验证器：

    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 示例。另请参阅 Portable Asset Compiler Kit (Pack) 库，该库可用于在设备上构建 APK，以搭配基于 Android 的验证器使用。

APK 大小

对于表盘推送表盘，应特别注意确保 APK 大小保持在最低限度：表盘 APK 可能会通过蓝牙从手机应用传输到手表应用，这可能会很慢。

过大的 APK 可能需要相当长的时间才能传输完毕，这不仅会带来糟糕的用户体验，还会消耗大量电池电量。

  • 使用 pngquant 等适当的库，尽可能缩小图片文件大小
    • 在表盘合集构建流程中包含此内容
    • 检查图片的尺寸是否适合其使用时的比例。
    • 确保图片经过适当裁剪，移除了所有周围背景。
  • 缩小字体文件的大小

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

APK 签名

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

架构

考虑系统的三个主要组成部分：

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

如需了解详情，请参阅数据层 API 指南。