開始使用 Health Connect

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

本指南說明如何開始在應用程式使用 Health Connect。

步驟 1：準備 Health Connect 應用程式

Health Connect 應用程式負責處理應用程式透過 Health Connect SDK 傳送的所有要求，包括儲存資料及管理其讀取和寫入權限。

Health Connect 的存取權取決於手機安裝的 Android 版本。下列各節會概述如何處理多個近期的 Android 版本。

Android 14

從 Android 14 (API 級別 34) 開始，Health Connect 是 Android 架構的一部分。此版本的 Health Connect 是「架構模組」，因此您不需要進行設定。

Android 13 以下版本

在 Android 13 (API 級別 33) 以下版本中，Health Connect 不屬於 Android 架構，因此您必須從 Google Play 商店安裝 Health Connect 應用程式。

如果您已在 Android 13 以下版本將應用程式與 Health Connect 整合，且想在 Android 14 執行遷移，請參閱「從 Android 13 遷移至 Android 14」。

開啟 Health Connect 應用程式

Health Connect 不再預設出現於主畫面。您可以透過「設定」開啟健康資料同步，但路徑會因 Android 版本而異：

  • Android 14 以上版本：依序前往「設定」>「安全性與隱私權」>「隱私權控制項」>「Health Connect」，或在「設定」中搜尋「Health Connect」。
  • Android 13 以下版本：依序前往「設定」>「應用程式」>「Health Connect」，或將 Health Connect 新增至「快速設定」選單。

步驟 2：在應用程式中加入 Health Connect SDK

Health Connect SDK 負責透過 Health Connect API，在執行中的作業內，傳送要求到 Health Connect 應用程式中的資料儲存庫。

在模組層級的 build.gradle 檔案中新增 Health Connect SDK 依附元件：

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha06"
  ...
}

如需查看最新版本，請參閱 Health Connect 版本。

connect-client 1.1.0 以上版本需要 compileSdk = 36 和 Android Gradle 外掛程式 (AGP) 8.9.1 以上版本。更新模組層級 build.gradle 檔案中的 compileSdk：

android {
  compileSdk = 36
}

使用初期測試版發布管道功能

如要使用 Canary 發布管道中的功能，請在模組層級 build.gradle 檔案中修改 compileSdk 的版本：

android {
  compileSdkPreview = "CANARY"
}

步驟 3：設定應用程式

以下各節說明如何設定應用程式，進而與 Health Connect 整合。

各項功能適用的國家/地區

當「健康資料同步」新增功能時，使用者不一定會更新「健康資料同步」版本。Feature Availability API 可用來檢查使用者的裝置是否支援健康資料同步中的功能，並決定要採取什麼行動。

用於檢查功能可用性的主要函式是 getFeatureStatus()。這會傳回整數常數 FEATURE_STATUS_AVAILABLE 或 FEATURE_STATUS_UNAVAILABLE：

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

宣告權限

存取健康與健身資料需搭配保護措施。Health Connect 導入讀取與寫入作業安全層，可提供使用者信任感。

在應用程式中，根據所需的資料類型，在 AndroidManifest.xml 檔案中宣告讀取和寫入權限，這些權限應與您在 Play 管理中心宣告存取權的資料類型相符。

Health Connect 使用標準 Android 權限聲明格式，請以 <uses-permission> 標記指派權限。然後，在 <manifest> 標記內建立巢狀結構。

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

如需權限及對應資料類型的完整清單，請參閱「資料類型清單」一文。

顯示應用程式的隱私權政策對話方塊

您的 Android 資訊清單必須有顯示應用程式隱私權政策的 Activity，也就是應用程式要求權限的理由，說明使用者資料的使用和處理方式。

當使用者在 Health Connect 權限畫面中點選「隱私權政策」連結時，請宣告這個活動以處理傳送至應用程式的 ACTION_SHOW_PERMISSIONS_RATIONALE 意圖。

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

取得 Health Connect 用戶端

HealthConnectClient 是 Health Connect API 的進入點。 它會允許應用程式在 Health Connect 應用程式中使用資料儲存庫，會自動管理自身與基礎儲存空間層的連線，並處理傳出要求與傳入回應的所有處理序間通訊 (IPC) 和序列化作業。

如要取得用戶端執行個體，請先在 Android 資訊清單中宣告 Health Connect 套件名稱。

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

接著在 Activity 中，使用 getSdkStatus 檢查是否已安裝健康資料同步。如果已安裝，請取得 HealthConnectClient 執行個體。

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

步驟 4：要求使用者授予權限

建立用戶端執行個體後，應用程式必須要求使用者授予權限。使用者必須能隨時授予或拒絕權限。 如要這麼做，請為所需資料類型建立一組權限。請務必先在 Android 資訊清單中聲明該組權限。 

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 使用 getGrantedPermissions 查看應用程式是否已取得所需權限。如果沒有，請使用 createRequestPermissionResultContract 要求這些權限。系統接著會顯示 Health Connect 權限畫面。 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 使用者隨時可以授予或撤銷權限，因此應用程式每次使用權限前都必須檢查權限，並處理權限遺失的情況。

引導使用者

許多應用程式都有自訂的新手上路流程，例如功能教學，或徵詢使用者同意。如要讓健康資料同步啟動新手上路流程，請在資訊清單中加入下列內容：

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

使用者可以直接從 Health Connect 應用程式啟動與應用程式的連線，而不必從應用程式內啟動。如果應用程式需要額外的互動，而不只是授予讀取或寫入資料的權限，請提供新手上路活動。

請注意，新手上路活動可能會多次啟動，例如使用者之後撤銷授予應用程式的權限，然後又重新連結，就會發生此情況。

步驟 5：執行作業

完成所有設定後，您可以在應用程式中執行讀取和寫入作業。

使用者可能會使用其他應用程式，將資料同步到健康資料同步，供您的應用程式存取。如果使用者尚未設定這些應用程式寫入 Health Connect，您可以使用 Matchmaking API，為使用者順暢連結這些應用程式。

寫入資料

請將資料整理成一份結構分明的記錄。建議您查看 Health Connect 可用的資料類型清單。

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

然後使用 insertRecords 寫入記錄。

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

讀取資料

您可以使用 readRecords 讀取個別資料。

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

您也可以使用 aggregate 以匯總方式讀取資料。

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

教學影片

請觀看以下影片，進一步瞭解 Health Connect 的各項功能，以及可實現流暢整合的最佳做法指南：

資源

請參閱下列資源，以利日後開發。

後續步驟

請參考常見工作流程，瞭解如何在 Health Connect 中執行作業，例如：