中繼資料相關規定

本指南適用於健康資料同步 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 導入了兩項中繼資料變更，有助於驗證生態系統中是否有其他實用的中繼資料。如果 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 類別會支援唯一裝置 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()

如果您在未宣告 WRITE_DEVICE_UDI 權限的情況下，使用 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")

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

如要使用測試程式庫，您需要在模組層級的 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。