元数据要求

本指南与健康数据共享 1.1.0-alpha12 及更高版本兼容。

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

库信息

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

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

元数据变更

自 1.1.0-alpha12 版起，健康数据共享 Jetpack SDK 中引入了两项元数据变更，以帮助验证生态系统中是否存在其他有用的元数据。如果 Record 构造函数中未包含 metadata，您可能会看到构造函数内部 错误。

指定记录方法

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

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

例如：

 StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata(),
    count = 10
)
HealthConnectManager.kt

设备类型

您必须为所有自动记录和主动记录的数据指定设备类型。如需了解详情，请参阅 Jetpack 文档中的 Device 类。目前的设备类型包括：

某些 Device.type 值仅在 Health Connect 的更高版本中提供。如果扩展设备类型功能不可用，这些类型将被视为 Device.TYPE_UNKNOWN。

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

  // Feature is available
} else {
  // Feature isn't available
}

例如：

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

// Phone
 val PHONE_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel 8",
    type = Device.TYPE_PHONE
)

// Ring
 val RING_DEVICE = Device(
    manufacturer = "Oura",
    model = "Ring Gen3",
    type = Device.TYPE_RING
)

// Scale
 val SCALE_DEVICE = Device(
    manufacturer = "Withings",
    model = "Body Comp",
    type = Device.TYPE_SCALE
)
HealthConnectManager.kt

代码段已更新

如果需要新代码段来满足新的元数据要求，健康数据共享 指南已更新。如需查看一些示例，请参阅 写入数据页面。

新的元数据方法

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

• 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 开源项目。

测试数据

使用 测试库 和 MetadataTestHelper 模拟预期元数据 值：

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

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

对于测试库，您需要将此健康数据共享 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。