中繼資料相關規定

本指南適用於 Health Connect 1.2.0-alpha05 以上版本。

如果開發人員升級至 1.1.0-alpha12 以上版本，健康資料同步的中繼資料會有所變更。

程式庫資訊

Google Maven Android Gradle 外掛程式構件 ID 會識別您需要升級的健康資料同步程式庫。在模組層級的 build.gradle 檔案中，新增以下健康資料同步 SDK 依附元件：

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

中繼資料變更

自 1.1.0-alpha12 版起，健康資料同步 Jetpack SDK 導入了兩項中繼資料變更，有助於驗證生態系統中是否存在其他實用的中繼資料。如果 Record 建構函式未包含 metadata，可能會看到「Constructor internal」錯誤。

指定記錄方式

每當 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 類別支援專屬裝置 ID (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) 指派給特定裝置型號的全球公認識別碼。
• 產品 ID (UDI-PI)：裝置專屬屬性，例如序號、批號、製造日期或到期日。

為保護使用者隱私，請僅在健康資料同步中填入代碼的 UDI-DI 部分。請勿加入任何產品 ID 屬性 (例如序號或批號)。

程式碼範例

注意：您可以在建構 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 的存在表示資料來自已註冊的醫療器材。判讀應用程式應查詢法規資料庫，例如美國食品藥物管理局的全球唯一裝置識別資料庫 (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")

這會模擬健康資料同步實作的行為，在插入記錄時自動填入這些值。

如要使用測試程式庫，請在模組層級的 build.gradle 檔案中，新增下列健康資料同步 SDK 依附元件：

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。