中繼資料相關規定

本指南適用於 Health Connect 1.1.0-alpha12 以上版本。

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

圖書館資訊

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

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

中繼資料變更

自 1.1.0-alpha12 版起，健康資料同步 Jetpack SDK 導入了兩項中繼資料變更，有助於驗證生態系統中是否存在其他實用的中繼資料。

指定錄製方法

每當例項化 Record() 型別物件時，您都必須指定中繼資料詳細資料。

將資料寫入健康資料同步時，您必須使用其中一個對應的工廠方法，例項化 Metadata，藉此指定四種記錄方法之一：

錄製方法 說明
RECORDING_METHOD_UNKNOWN 無法驗證錄音方式。
RECORDING_METHOD_MANUAL_ENTRY 使用者輸入資料。
RECORDING_METHOD_AUTOMATICALLY_RECORDED 裝置或感應器記錄了資料。
RECORDING_METHOD_ACTIVELY_RECORDED 使用者在裝置上啟動或結束錄製工作階段。

例如：

StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata.manualEntry(),
    Count = 10,
)

裝置類型

您必須為所有自動和主動記錄的資料指定裝置類型。雖然也可以指定 manufacturer 和 model，但這些是選用欄位。詳情請參閱 Jetpack 說明文件中的 Device 類別。目前的裝置類型包括：

裝置類型 說明
TYPE_UNKNOWN 裝置類型不明。
TYPE_WATCH 裝置類型為手錶。
TYPE_PHONE 裝置類型為手機。
TYPE_SCALE 裝置類型為體重計。
TYPE_RING 裝置類型為智慧指環。
TYPE_HEAD_MOUNTED 裝置類型為頭戴式裝置。
TYPE_FITNESS_BAND 裝置類型為健身手環。
TYPE_CHEST_STRAP 裝置類型為胸帶。
TYPE_SMART_DISPLAY 裝置類型為智慧螢幕。

部分 Device.type 值僅適用於新版「健康資料同步」。如果無法使用擴充裝置類型功能，系統會將這些類型視為 Device.TYPE_UNKNOWN。

擴充裝置類型 說明
TYPE_CONSUMER_MEDICAL_DEVICE 裝置類型為醫療器材。
TYPE_GLASSES 裝置類型為智慧眼鏡或眼鏡。
TYPE_HEARABLE 裝置類型為助聽裝置。
TYPE_FITNESS_MACHINE 裝置類型為固定式機器。
TYPE_FITNESS_EQUIPMENT 裝置類型為健身器材。
TYPE_PORTABLE_COMPUTER 裝置類型為可攜式電腦。
TYPE_METER 裝置類型為測量儀表。
如要判斷使用者的裝置是否支援 Health Connect 的擴充裝置類型，請檢查用戶端是否提供 FEATURE_EXTENDED_DEVICE_TYPES：

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

  // Feature is available
} else {
  // Feature isn't available
}
如要瞭解詳情，請參閱「查看功能支援情形」。

請盡可能提供裝置製造商和型號，以及裝置類型。例如：

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

已更新摘要

凡是需要新程式碼片段來遵守新中繼資料規定的「健康資料同步」指南，都已更新完畢。如需範例，請參閱「寫入資料」頁面。

新的中繼資料方法

中繼資料無法再直接例項化，因此請使用其中一種工廠方法取得新的中繼資料例項。工廠方法會驗證裝置或感應器是否在記錄資料時提供裝置資訊。如果是手動輸入的資料，裝置資訊仍為選填項目。每個函式都有三種簽章變體：

  • 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 檔案中新增這個 Health Connect 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。