元数据要求

对于升级到 1.1.0-alpha12 版或更高版本的开发者，健康数据共享中的元数据有所变化。

影视库信息

Google Maven Android Gradle 插件工件 ID 用于标识您需要升级到的健康数据共享库。 将此 Health Connect SDK 依赖项添加到模块级 build.gradle 文件中：

dependencies {
  implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}

元数据更改

自版本 1.1.0-alpha12 起，Health Connect Jetpack SDK 中引入了两项元数据变更，以帮助验证生态系统中是否存在其他有用的元数据。

指定录制方法

每当实例化 Record() 类型对象时，您都需要指定元数据详细信息。

将数据写入健康数据共享时，您必须使用相应的工厂方法实例化 Metadata，以指定四种记录方法之一：

录制方法 说明
RECORDING_METHOD_UNKNOWN 无法验证录制方法。
RECORDING_METHOD_MANUAL_ENTRY 用户输入了数据。
RECORDING_METHOD_AUTOMATICALLY_RECORDED 设备或传感器记录了数据。
RECORDING_METHOD_ACTIVELY_RECORDED 用户在设备上发起录制会话的开始或结束。

例如：

StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata.manualEntry(),
    Count = 10,
)

设备类型

您必须为所有自动和主动记录的数据指定设备类型。虽然也可以指定 manufacturer 和 model，但它们是可选的。如需了解详情，请参阅 Jetpack 文档中的 Device 类。当前设备类型包括：

设备类型 说明
TYPE_UNKNOWN 设备类型未知。
TYPE_WATCH 设备类型为手表。
TYPE_PHONE 设备类型是手机。
TYPE_SCALE 设备类型为体重秤。
TYPE_RING 设备类型为指环。
TYPE_HEAD_MOUNTED 设备类型为头戴式设备。
TYPE_FITNESS_BAND 设备类型为健身手环。
TYPE_CHEST_STRAP 设备类型为胸带。
TYPE_SMART_DISPLAY 设备类型为智能显示屏。

部分 Device.type 值仅在较新版本的“健康数据共享”中提供。如果扩展设备类型功能不可用，这些类型将被视为 Device.TYPE_UNKNOWN。

扩展设备类型 说明
TYPE_CONSUMER_MEDICAL_DEVICE 设备类型为医疗设备。
TYPE_GLASSES 设备类型是智能眼镜或眼镜。
TYPE_HEARABLE 设备类型为可穿戴音频设备。
TYPE_FITNESS_MACHINE 设备类型为固定式器械。
TYPE_FITNESS_EQUIPMENT 设备类型为健身器材。
TYPE_PORTABLE_COMPUTER 设备类型为便携式计算机。
TYPE_METER 设备类型为测量仪表。
如需确定用户的设备是否支持 Health Connect 上的扩展设备类型，请检查客户端上 FEATURE_EXTENDED_DEVICE_TYPES 的可用性：

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_EXTENDED_DEVICE_TYPES
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}
如需了解详情，请参阅查看功能可用性。

请尽可能提供设备的制造商和型号，以及设备类型。例如：

private val TEST_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel Watch",
    type = Device.TYPE_WATCH
)

摘要已更新

我们已在需要新代码段的地方更新了健康数据共享指南，以符合新的元数据要求。如需查看一些示例，请参阅写入数据页面。

新的元数据方法

元数据不再能直接实例化，因此请使用某个工厂方法来获取新的元数据实例。工厂方法会验证在设备或传感器用于记录数据时是否提供了设备信息。对于手动输入的数据，提供设备信息仍然是可选操作。 每个函数都有三种签名变体：

  • activelyRecorded

    • fun activelyRecorded(device: Device): Metadata.
    • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
    • fun activelyRecordedWithId(id: String, device: Device): Metadata

  • autoRecorded

    • fun autoRecorded(device: Device): Metadata
    • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
    • fun autoRecordedWithId(id: String, device: Device): Metadata

  • manualEntry

    • fun manualEntry(device: Device? = null): Metadata
    • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
    • fun manualEntryWithId(id: String, device: Device? = null): Metadata

  • unknownRecordingMethod

    • fun unknownRecordingMethod(device: Device? = null): Metadata
    • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
    • fun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata

如需了解详情，请参阅 Android 开源项目。

测试数据

使用 Testing Library 和 MetadataTestHelper 模拟预期元数据值：

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

这会模拟健康数据共享实现的行为，即在插入记录期间自动填充这些值。

对于测试库，您需要将此 Health Connect SDK 依赖项添加到模块级 build.gradle 文件中：

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

升级库

您需要执行的主要步骤如下：

  1. 将库升级到 1.1.0-alpha12。

  2. 构建库时，如果需要新的元数据，系统会抛出编译错误。如需解决这些错误并完成迁移，请确认您已进行以下更改：

    • 构造 Record 时，必须指定记录方法。为此，请使用 Metadata 中提供的工厂方法之一，例如 Metadata.manualEntry() 或 Metadata.activelyRecorded(device = Device(...))。
    • 对于设备记录的数据，必须指定设备类型，例如 Device.TYPE_WATCH 或 Device.TYPE_PHONE。

  3. 如果您的应用写入了扩展设备类型，请使用 FEATURE_EXTENTED_DEVICE_TYPES 将其门控，以避免在不支持该功能的设备上出现意外的 TYPE_UNKNOWN。