1. 簡介
上次更新時間：2022 年 9 月 21 日
什麼是 Health Connect？
Health Connect 是一個適用於 Android 應用程式開發人員的健康資料平台，透過單一的整合式介面存取使用者的健康和保健資料，並在所有裝置上使用一致的功能行為。藉助 Health Connect，使用者可在裝置上安全儲存健康和保健資料，並且完全掌控存取權，實現透明的存取。
Health Connect 的運作方式
Health Connect 支援超過 50 種常見的健康和健身資料類型和類別，包括活動、睡眠、營養、身體測量資料，以及心率和血壓等生命徵象。
透過使用者權限，開發人員使用標準化的結構定義和 API 行為，安全地從 Health Connect 讀取資料以及向 Health Connect 寫入資料。使用者將使用精細的控制項完全掌控自己的隱私權設定，以便隨時查看哪些應用程式要求存取資料。Health Connect 中的資料會儲存在裝置上並進行加密。使用者能夠關閉他們在裝置上不需要的資料的存取權或刪除這些資料，並可選擇在使用多個應用程式時優先處理其中一個資料來源。
Health Connect 架構
以下將說明 Health Connect 的重要面向和架構元件：
- 用戶端應用程式 - 如要與 Health Connect 整合，用戶端應用程式必須先將 SDK 連結至其健康與健身應用程式。這樣做即可提供用來與 Health Connect API 互動的 API 介面。
- 軟體開發套件 - 這個 SDK 可讓用戶端應用程式透過 IPC 與 Health Connect APK 進行通訊。
- Health Connect APK - 這是實作 Health Connect 的 APK，其中包含權限管理和資料管理元件。使用者的裝置會直接提供 Health Connect APK，這表示 Health Connect 是以裝置為中心，而非以帳戶為中心。
- 權限管理 - Health Connect 提供使用者介面，應用程式可透過該介面向使用者要求顯示資料所需的權限。此外，Health Connect 也提供現有的使用者權限清單，讓使用者能夠輕鬆掌控及管理自己對不同應用程式授予或拒絕的存取權。
- 資料管理 - Health Connect 提供的使用者介面可列出記錄資料總覽，無論是使用者的步數、自行車速度、心率或其他支援的資料類型，都能一目瞭然。
建構項目
在這個程式碼研究室中，您會建構一個與 Health Connect 整合的簡單的健康與健身應用程式。您的應用程式將會：
- 取得及查看使用者的資料存取權
- 將資料寫入 Health Connect
- 讀取 Health Connect 的匯總資料
課程內容
- 如何設定環境來支援 Health Connect 整合開發
- 如何取得權限並執行權限檢查
- 如何將健康與健身資料提供給 Health Connect 平台
- 在裝置上儲存資料的好處
- 如何使用 Google 提供的開發人員工具驗證應用程式
軟硬體需求
- 最新的 Android Studio 穩定版
- 搭載 Android SDK 28 (Pie) 以上版本的 Android 行動裝置
2. 開始設定
安裝 Health Connect
您可以在 Play 商店下載 Health Connect，並在行動裝置上安裝 Health Connect，以處理應用程式透過 Health Connect SDK 傳送的所有要求。掃描下方 QR 圖碼即可安裝 Health Connect。
取得範例程式碼
範例目錄包含這個程式碼研究室的 start 和 finished 程式碼。您會在 Android Studio 左側的「專案」檢視畫面中，看到兩個模組：
- start – 這是本專案的範例程式碼，您修改後才能完成這個程式碼研究室的步驟
- finished – 這個程式碼研究室完成後的程式碼；可用來檢查您的成果
探索 start 程式碼
程式碼研究室範例應用程式顯示 Jetpack Compose 的基本 UI 以及下列畫面：
WelcomeScreen是應用程式的到達網頁，根據 Health Connect 的供應情形 (已安裝、未安裝、不支援) 顯示不同的訊息。PrivacyPolicyScreen說明應用程式的權限使用情形，當使用者在 Health Connect 權限對話方塊中按一下「隱私權政策」連結時向使用者顯示。InputReadingsScreen説明如何讀取及寫入簡單的體重記錄。ExerciseSessionScreen允許插入及列出運動時段。使用者點選記錄後，系統會將使用者導向ExerciseSessionDetailScreen，並顯示與該時段相關的更多資料。DifferentialChangesScreen說明如何取得變更憑證權杖以及 Health Connect 新的變更內容。
HealthConnectManager 會儲存與 Health Connect 互動的所有函式。在這個程式碼研究室中，我們會逐步引導您完成常用功能。start 程式碼中的 <!-- TODO: 字串在這個程式碼研究室中具有對應的部分，提供範例程式碼供您插入到專案中。
首先，請將 Health Connect 新增至專案！
新增 Health Connect 用戶端 SDK
如要開始使用 Health Connect SDK，您必須在 build.gradle 檔案中新增依附元件。如要尋找最新版本的 Health Connect，請參閱 Jetpack 程式庫版本。
dependencies {
// Add a dependency of Health Connect SDK
implementation "androidx.health.connect:connect-client:1.0.0-alpha06"
}
宣告 Health Connect 瀏覽權限
如要在應用程式中與 Health Connect 互動，請在 AndroidManifest.xml 中宣告 Health Connect 套件名稱：
<!-- TODO: declare Health Connect visibility -->
<queries>
<package android:name="com.google.android.apps.healthdata" />
</queries>
執行 start 專案
此時，您應該會看到顯示「已在此裝置上安裝 Health Connect」的歡迎畫面和選單導覽匣。我們會新增功能，在後續章節中與 Health Connect 互動。
3. 權限控制
Health Connect 建議開發人員將權限要求限制為應用程式使用的資料類型。大量權限要求會減少使用者對應用程式的信心，並降低使用者的信任。如果權限遭拒超過兩次，系統將鎖定應用程式 (例如，不會再顯示權限要求)。
以本次程式碼研究室為例，我們只需要下列權限：
- 運動時段
- 心跳速率
- 操作步驟
- 卡路里燃燒總量
- 體重
宣告權限
宣告應用程式要使用的權限。在 res/values/health_permissions.xml 中建立陣列資源。您可以前往這裡查看資料類型與權限的完整對應。請注意，您必須為應用程式要使用的每項權限新增一行：
<!-- TODO: declare Health Connect permissions -->
<resources>
<array name="health_permissions">
<item>androidx.health.permission.ExerciseSession.READ</item>
<item>androidx.health.permission.ExerciseSession.WRITE</item>
<item>androidx.health.permission.Steps.READ</item>
<item>androidx.health.permission.Steps.WRITE</item>
<item>androidx.health.permission.HeartRate.READ</item>
<item>androidx.health.permission.HeartRate.WRITE</item>
<item>androidx.health.permission.Weight.READ</item>
<item>androidx.health.permission.Weight.WRITE</item>
<item>androidx.health.permission.TotalCaloriesBurned.READ</item>
<item>androidx.health.permission.TotalCaloriesBurned.WRITE</item>
</array>
</resources>
在 AndroidManifest.xml 中宣告資源：
<!-- TODO: Required to specify which Health Connect permissions the app can request -->
<meta-data
android:name="health_permissions"
android:resource="@array/health_permissions"/>
在 AndroidManifest.xml 中宣告下列意圖篩選器，以處理說明應用程式使用權限的意圖。應用程式必須處理此意圖，並顯示隱私權政策，說明使用者資料的使用方式和處理方式。當使用者按一下 Health Connect 權限對話方塊中的「隱私權政策」連結時，系統就會傳送此意圖至應用程式。
<!-- TODO: Add intent filter to handle permission rationale intent -->
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
現在，請重新執行應用程式，以查看宣告的權限。按一下選單導覽匣中的「Settings」，即可前往 Health Connect 設定畫面。按一下「App permissions」，清單中會顯示「Health Connect Codelab」。按一下「Health Connect Codelab」(Health Connect 程式碼研究室)，系統會列出讀取和寫入權限的資料類型。
要求權限
除了直接將使用者帶到 Health Connect 設定畫面以管理權限外，您也可以透過 Health Connect API 向應用程式要求權限。在程式碼研究室專案中，我們會先傳送權限要求，然後再讀取或寫入資料。
HealthConnectClient 是 Health Connect API 的進入點。在 HealthConnectManager.kt 中，取得 HealthConnectClient 執行個體。
private val healthConnectClient by lazy { HealthConnectClient.getOrCreate(context) }
如要在應用程式內啟動要求權限對話方塊，請先為所需資料類型建構一組權限。請只針對您要使用的資料類型要求權限。舉例來說，在記錄體重畫面中，您只需要授予 Weight 的讀取及寫入權限。我們已在 InputReadingsViewModel.kt 中建立權限集，如下所示。
val permissions = setOf(
HealthPermission.createReadPermission(WeightRecord::class),
HealthPermission.createWritePermission(WeightRecord::class),
)
接著，請先檢查是否已獲授予相關權限，再啟動權限要求。在 HealthConnectManager.kt 中，使用 getGrantedPermissions 檢查是否已授予必要資料類型的權限。如要啟動權限要求，您必須先使用 Health Connect SDK 的 PermissionController.createRequestPermissionResultContract() 建立 ActivityResultContract，然後在未獲授予所需權限的情況下啟動。
suspend fun hasAllPermissions(permissions: Set<HealthPermission>): Boolean {
return permissions == healthConnectClient.permissionController.getGrantedPermissions(
permissions
)
}
fun requestPermissionsActivityContract(): ActivityResultContract<Set<HealthPermission>, Set<HealthPermission>> {
return PermissionController.createRequestPermissionResultContract()
}
如果您未獲授予必要資料類型的相關權限，在程式碼研究室的範例應用程式中，畫面上可能會顯示「Request permissions」(要求權限) 按鈕。按一下「Request permissions」按鈕後，系統會將您導向 Health Connect 權限對話方塊。請授予所需權限，並返回程式碼研究室應用程式。
4. 寫入資料
開始將記錄寫入 Health Connect。如要寫入 Weight 記錄，請使用體重輸入值建立 WeightRecord 物件。請注意，Health Connect SDK 支援多種單元類別，例如使用 Mass.kilograms(weightInput) 設定使用者的體重 (以公斤為單位)。
所有寫入 Health Connect 的資料都必須指定時區偏移資訊。寫入資料的同時指定時區偏移資訊，在 Health Connect 中讀取資料時可提供時區資訊。
建立體重記錄後，請使用 healthConnectClient.insertRecords 將資料寫入 Health Connect。
/**
* TODO: Writes [WeightRecord] to Health Connect.
*/
suspend fun writeWeightInput(weightInput: Double) {
val time = ZonedDateTime.now().withNano(0)
val weightRecord = WeightRecord(
weight = Mass.kilograms(weightInput),
time = time.toInstant(),
zoneOffset = time.offset
)
val records = listOf(weightRecord)
try {
healthConnectClient.insertRecords(records)
Toast.makeText(context, "Successfully insert records", Toast.LENGTH_SHORT).show()
} catch (e: Exception) {
Toast.makeText(context, e.message.toString(), Toast.LENGTH_SHORT).show()
}
}
現在執行應用程式。按一下「Record weight」，並輸入新的體重記錄 (以公斤為單位)。如要驗證體重記錄是否已成功寫入 Health Connect，請開啟 Health Connect 設定，然後依序點選「Data and access」 ->「Body measurements」 ->「Weight」 ->「See all entries」。您應該會看到從 Health Connect 程式碼研究室寫入的新的體重記錄。
寫入運動時段
時段是指一段時間間隔，而使用者會在此期間執行特定活動。Health Connect 中的運動時段可以包含從跑步到打羽毛球等任何活動。使用者可利用時段，依據時間來評估成效。這項資料會記錄在一段時間內測量的一系列即時樣本，例如特定活動期間的連續心率或位置樣本。
以下範例說明如何寫入運動時段。使用 healthConnectClient.insertRecords 插入與時段關聯的多個資料記錄。這個範例中的插入要求包括帶有 ExerciseType 的 ExerciseSessionRecord、帶有步數計算的 StepsRecord、帶有 Energy 的 TotalCaloriesBurnedRecord 和一系列 HeartRateRecord 範例。
/**
* TODO: Writes an [ExerciseSessionRecord] to Health Connect.
*/
suspend fun writeExerciseSession(start: ZonedDateTime, end: ZonedDateTime) {
healthConnectClient.insertRecords(
listOf(
ExerciseSessionRecord(
startTime = start.toInstant(),
startZoneOffset = start.offset,
endTime = end.toInstant(),
endZoneOffset = end.offset,
exerciseType = ExerciseSessionRecord.ExerciseType.RUNNING,
title = "My Run #${Random.nextInt(0, 60)}"
),
StepsRecord(
startTime = start.toInstant(),
startZoneOffset = start.offset,
endTime = end.toInstant(),
endZoneOffset = end.offset,
count = (1000 + 1000 * Random.nextInt(3)).toLong()
),
TotalCaloriesBurnedRecord(
startTime = start.toInstant(),
startZoneOffset = start.offset,
endTime = end.toInstant(),
endZoneOffset = end.offset,
energy = Energy.calories((140 + Random.nextInt(20)) * 0.01)
)
) + buildHeartRateSeries(start, end)
)
}
/**
* TODO: Build [HeartRateRecord].
*/
private fun buildHeartRateSeries(
sessionStartTime: ZonedDateTime,
sessionEndTime: ZonedDateTime,
): HeartRateRecord {
val samples = mutableListOf<HeartRateRecord.Sample>()
var time = sessionStartTime
while (time.isBefore(sessionEndTime)) {
samples.add(
HeartRateRecord.Sample(
time = time.toInstant(),
beatsPerMinute = (80 + Random.nextInt(80)).toLong()
)
)
time = time.plusSeconds(30)
}
return HeartRateRecord(
startTime = sessionStartTime.toInstant(),
startZoneOffset = sessionStartTime.offset,
endTime = sessionEndTime.toInstant(),
endZoneOffset = sessionEndTime.offset,
samples = samples
)
}
5. Health Connect Toolbox
Health Connect Toolbox 簡介
Health Connect Toolbox 是一款隨附的開發人員工具，可協助您輕鬆測試應用程式與 Health Connect 的整合。Health Connect Toolbox 可讓您輕鬆地從 Health Connect 直接讀取資料並將資料寫入其中，以便輕鬆測試應用程式的 CRUD 作業。
在這個程式碼研究室中，我們會使用 Health Connect Toolbox 來測試您剛剛實作的讀取和寫入功能。
設定 Health Connect Toolbox
使用 adb 在已連結的裝置上安裝 Toolbox APK，指令如下：
$ adb install HealthConnectToolbox-{Version Number}.apk
當您首次開啟 Health Connect Toolbox 應用程式時，系統會將您導向「Apps」>「Special app access」>「Display over other apps」下的權限設定。這項權限可讓 Health Connect Toolbox 在其他應用程式上層顯示重疊元素，因此您不必離開正在開發的應用程式，即可輕鬆測試資料的讀取和寫入。
接著，在 Toolbox 的主畫面中開啟 Health Connect 應用程式，或是直接前往權限流程允許所有 Health Connect 讀取和寫入權限，以便稍後進行測試。
讀取和寫入健康記錄
Health Connect Toolbox 支援讀取和寫入所有 Health Connect 資料類型。在程式碼研究室的最後一個工作階段中，您已成功將體重和運動時段記錄寫入 Health Connect。請檢查是否能讀取 Health Connect Toolbox 中的資料。
必須先取得使用者的許可，才能在 Health Connect 中讀寫資料。Health Connect Toolbox 也是如此。首先，請接受 Health Connect Toolbox 的權限要求。接著，按一下疊加選單中的搜尋圖示 
開啟對話方塊，選取資料類型 (例如體重)，然後按一下「READ HEALTH RECORD」按鈕。您應該會在程式碼研究室範例應用程式中看到您剛剛寫入 Health Connect 的記錄。
如要將記錄插入 Health Connect，請按一下疊加選單中的編輯圖示 
開啟對話方塊，然後選取資料類型。讓我們從 Toolbox 插入體重記錄。在下一堂課中，我們會說明如何透過 Health Connect API 讀取記錄以及在應用程式中顯示資料。
6. 讀取資料
現在您已使用程式碼研究室範例應用程式或 Toolbox 應用程式寫入體重和運動時段記錄。讓我們使用 Health Connect API 讀取這些記錄。請先建立 ReadRecordsRequest 並指定記錄類型和讀取記錄的時間範圍。ReadRecordsRequest 也可以設定 dataOriginFilter，以指定要讀取記錄的來源應用程式。
/**
* TODO: Reads in existing [WeightRecord]s.
*/
suspend fun readWeightInputs(start: Instant, end: Instant): List<WeightRecord> {
val request = ReadRecordsRequest(
recordType = WeightRecord::class,
timeRangeFilter = TimeRangeFilter.between(start, end)
)
val response = healthConnectClient.readRecords(request)
return response.records
}
/**
* TODO: Obtains a list of [ExerciseSessionRecord]s in a specified time frame.
*/
suspend fun readExerciseSessions(start: Instant, end: Instant): List<ExerciseSessionRecord> {
val request = ReadRecordsRequest(
recordType = ExerciseSessionRecord::class,
timeRangeFilter = TimeRangeFilter.between(start, end)
)
val response = healthConnectClient.readRecords(request)
return response.records
}
現在執行應用程式，看看是否顯示體重記錄和運動時段清單。
7. 讀取差異化資料
Health Connect 差異化變更 API 可協助您追蹤一組資料類型在特定時間點的變更。舉例來說，如果您想瞭解使用者是否已更新或刪除應用程式中的任何現有記錄，以便據此更新資料庫。
只有在前景執行的應用程式才能使用 Health Connect 讀取資料。這項限制旨在進一步強化使用者隱私。系統會通知使用者，並向他們保證 Health Connect 不具備使用者資料的背景讀取權限，而且只會在前景讀取及使用這些資料。應用程式在前景運作時，差異化變更 API 可讓開發人員透過部署變更憑證權杖，以擷取對 Health Connect 所做的變更。
HealthConnectManager.kt 中有兩個函式 getChangesToken() 和 getChanges()，我們會在這些函式中新增差異化變更 API，以便取得資料變更。
初始變更憑證權杖設定
只有當應用程式透過變更憑證權杖要求時，系統才會從 Health Connect 擷取資料變更。變更憑證權杖代表修訂版本記錄中取得差異化資料的時間點。
如要取得變更憑證權杖，請傳送 ChangesTokenRequest 以及您要追蹤資料變更的一組資料類型。保留權杖，當您要從 Health Connect 擷取任何更新時使用權杖。
/**
* TODO: Obtains a changes token for the specified record types.
*/
suspend fun getChangesToken(): String {
return healthConnectClient.getChangesToken(
ChangesTokenRequest(
setOf(
ExerciseSessionRecord::class,
StepsRecord::class,
TotalCaloriesBurnedRecord::class,
HeartRateRecord::class,
WeightRecord::class
)
)
)
}
使用變更憑證權杖更新資料
如要取得應用程式上次與 Health Connect 同步處理以來的變更，請使用先前取得的變更憑證權杖，並使用權杖傳送 getChanges 呼叫。ChangesResponse 將從 Health Connect 獲取觀察到的 UpsertionChange 和 DeletionChange 清單。
/**
* TODO: Retrieve changes from a changes token.
*/
suspend fun getChanges(token: String): Flow<ChangesMessage> = flow {
var nextChangesToken = token
do {
val response = healthConnectClient.getChanges(nextChangesToken)
if (response.changesTokenExpired) {
throw IOException("Changes token has expired")
}
emit(ChangesMessage.ChangeList(response.changes))
nextChangesToken = response.nextChangesToken
} while (response.hasMore)
emit(ChangesMessage.NoMoreChanges(nextChangesToken))
}
接著，執行應用程式並前往「變更」畫面。請先啟用「Track changes」切換鈕，以取得變更憑證權杖。然後從 Toolbox 或程式碼研究室應用程式插入體重或運動時段。返回「Changes」畫面並按一下「Get new changes」按鈕，應該就能看到更新項目變更。
8. 匯總資料
Health Connect 也會透過匯總 API 提供匯總資料。以下範例說明如何從 Health Connect 取得累計和統計資料。
使用 healthConnectClient.aggregate 傳送 AggregateRequest。在匯總要求中，指定一組匯總指標和您取得匯總資料的時間範圍。例如，ExerciseSessionRecord.ACTIVE_TIME_TOTAL 和 StepsRecord.COUNT_TOTAL 等累計資料，以及 WeightRecord.WEIGHT_AVG、HeartRateRecord.BPM_MAX 和 HeartRateRecord.BPM_MIN 等統計資料。
/**
* TODO: Returns the weekly average of [WeightRecord]s.
*/
suspend fun computeWeeklyAverage(start: Instant, end: Instant): Mass? {
val request = AggregateRequest(
metrics = setOf(WeightRecord.WEIGHT_AVG),
timeRangeFilter = TimeRangeFilter.between(start, end)
)
val response = healthConnectClient.aggregate(request)
return response[WeightRecord.WEIGHT_AVG]
}
本例說明如何取得特定運動時段的相關匯總資料。請先使用具有 uid 的 healthConnectClient.readRecord 讀取記錄。然後使用運動時段的 startTime 和 endTime 做為時間範圍，並使用 dataOrigin 做為篩選條件來讀取相關的匯總資料。
/**
* TODO: Reads aggregated data and raw data for selected data types, for a given [ExerciseSessionRecord].
*/
suspend fun readAssociatedSessionData(
uid: String,
): ExerciseSessionData {
val exerciseSession = healthConnectClient.readRecord(ExerciseSessionRecord::class, uid)
// Use the start time and end time from the session, for reading raw and aggregate data.
val timeRangeFilter = TimeRangeFilter.between(
startTime = exerciseSession.record.startTime,
endTime = exerciseSession.record.endTime
)
val aggregateDataTypes = setOf(
ExerciseSessionRecord.ACTIVE_TIME_TOTAL,
StepsRecord.COUNT_TOTAL,
TotalCaloriesBurnedRecord.ENERGY_TOTAL,
HeartRateRecord.BPM_AVG,
HeartRateRecord.BPM_MAX,
HeartRateRecord.BPM_MIN,
)
// Limit the data read to just the application that wrote the session. This may or may not
// be desirable depending on the use case: In some cases, it may be useful to combine with
// data written by other apps.
val dataOriginFilter = setOf(exerciseSession.record.metadata.dataOrigin)
val aggregateRequest = AggregateRequest(
metrics = aggregateDataTypes,
timeRangeFilter = timeRangeFilter,
dataOriginFilter = dataOriginFilter
)
val aggregateData = healthConnectClient.aggregate(aggregateRequest)
val heartRateData = readData<HeartRateRecord>(timeRangeFilter, dataOriginFilter)
return ExerciseSessionData(
uid = uid,
totalActiveTime = aggregateData[ExerciseSessionRecord.ACTIVE_TIME_TOTAL],
totalSteps = aggregateData[StepsRecord.COUNT_TOTAL],
totalEnergyBurned = aggregateData[TotalCaloriesBurnedRecord.ENERGY_TOTAL],
minHeartRate = aggregateData[HeartRateRecord.BPM_MIN],
maxHeartRate = aggregateData[HeartRateRecord.BPM_MAX],
avgHeartRate = aggregateData[HeartRateRecord.BPM_AVG],
heartRateSeries = heartRateData,
)
}
接著，執行應用程式，查看「Record weight」畫面是否顯示平均體重。此外，如要查看運動時段的詳細資料，請開啟「Exercise sessions」畫面，然後輕觸其中一個運動時段記錄。
9. 恭喜
恭喜，您已成功建構第一個 Health Connect 整合式健康與健身應用程式。
應用程式可以宣告權限，並要求使用者在應用程式中使用的資料類型，還可以從 Health Connect 資料儲存空間讀取和寫入資料。此外，您還學習了如何在 Health Connect 資料儲存空間中建立模擬資料，以使用 Health Connect Toolbox 來支援應用程式的開發。
現在，您已瞭解讓健康與健身應用程式成為 Health Connect 生態系統組成部分的重要步驟。