中繼資料相關規定

本指南適用於 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() 型別物件時，您都必須指定中繼資料詳細資料。

將資料寫入「健康資料同步」時，必須指定下列四種記錄方法之一：

錄製方法 說明
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,
)

您必須為所有自動和主動記錄的資料指定裝置類型。目前的裝置類型包括：

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

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

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 模擬預期的中繼資料值：

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() 型別物件時，請務必實作必要的中繼資料變更。這樣應該就能完成遷移作業。