元数据要求

本指南适用于健康数据共享版本 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 中引入了两项元数据更改，以帮助验证生态系统中是否存在其他有用的元数据。如果 metadata 未包含在 Record 构造函数中，您可能会看到构造函数内部错误。

指定录制方法

每当实例化 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 值仅在较新版本的健康数据共享中提供。如果扩展设备类型功能不可用，这些类型将被视为 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 开源项目。

测试数据

使用 Testing Library 和 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。