元数据要求

本指南适用于 健康数据共享 1.2.0-alpha05 或更高版本。

对于升级到 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.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    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

唯一设备标识符 (UDI)

对于 Android 17（API 级别 37.1）或 U 扩展程序 23 或更高版本上的“健康数据共享”，Device 类包含对唯一设备标识符 (UDI) 的支持。将医疗设备的注册 UDI 模型详细信息与您的书面记录相关联，可让下游应用（例如远程医疗平台或临床门户）识别临床级读数，并将其与一般消费级穿戴式设备数据区分开来。

声明权限

如需将 UDI 详细信息写入健康数据共享，您必须在应用的 AndroidManifest.xml 文件中声明 WRITE_DEVICE_UDI 权限：

<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />

请注意，WRITE_DEVICE_UDI 是一项正常权限。您必须在清单中声明该权限，但无需在运行时向用户请求该权限。系统会在安装时自动向您的应用授予此权限。

仅填写设备标识符 (DI) 部分

完整的 UDI 包含两部分：

• 设备标识符 (UDI-DI)：由发证机构（例如 GS1）分配给特定设备型号的全球公认标识符。
• 生产标识符 (UDI-PI)：特定于单元的属性，例如序列号、批号、生产日期或失效日期。

为保护用户隐私，请仅在健康数据共享中填充代码的 UDI-DI 部分。请勿包含任何商品标识码属性（例如序列号或批号）。

代码示例

注意：您可以在构建 Device 实例时设置 UDI。

val device = Device(
    type = Device.TYPE_CONSUMER_MEDICAL_DEVICE,
    manufacturer = "Omron",
    model = "HEM-7121",
    udi = "04015674011832" // Device Identifier (UDI-DI) portion only
)

val device = Device.Builder()
    .setType(Device.DEVICE_TYPE_CONSUMER_MEDICAL_DEVICE)
    .setManufacturer("Omron")
    .setModel("HEM-7121")
    .setUdi("04015674011832") // Device Identifier (UDI-DI) portion only
    .build()

如果您在写入包含 UDI 的数据时未声明 WRITE_DEVICE_UDI 权限，健康数据共享 会在写入时抛出 SecurityException。

使用 UDI 验证设备是否已获批

“健康数据共享”充当传输层，不会验证 UDI 的真实性或注册状态。

对于数据读取器，UDI 的存在表示数据来自已注册的医疗设备。读取应用应查询监管数据库，例如 FDA 的全球唯一设备标识数据库 (GUDID) 或欧盟的 EUDAMED，以验证设备分类、监管许可状态（例如 I 类、II 类或 III 类）或特定预期用途。

摘要已更新

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

新增的元数据方法

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

• 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。