開始使用

開始安裝 Health Connect 之前，請先參考下列資源。

資源

Health Connect SDK (適用於 Jetpack)。只要在應用程式中加入這個 SDK，即可使用 Health Connect API。
API 參考資料。請參閱適用於 Health Connect API 的 Jetpack 參考資料。
API 要求開發人員聲明表單。表單要求讀取及/或寫入資料類型的存取權。
GitHub 程式碼範例和程式碼研究室 (選用) 請查看 GitHub 程式碼範例存放區和程式碼研究室，瞭解如何開始使用。

只要按照下列快速簡單的步驟進行，即可與 Health Connect 整合：

步驟 0：安裝 Health Connect

透過 Google Play 商店在裝置上安裝 Health Connect by Android。該程式可處理應用程式透過 Health Connect SDK 傳送的所有要求。

步驟 1：將 Health Connect SDK 新增至您的應用程式

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.0.0-alpha10"
  ...
}

您可以在版本資訊中找到最新版本。

步驟 2：取得 Health Connect 用戶端

HealthConnectClient 是 Health Connect API 的進入點。

以下提供 Health Connect 連線程序的逐步說明：

如要在應用程式中與 Health Connect 互動，請在 AndroidManifest.xml 檔案中宣告 Health Connect 套件名稱：

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

請檢查是否已安裝 Health Connect。如果已安裝，請取得 HealthConnectClient 執行個體。
```
if (HealthConnectClient.isProviderAvailable(context)) {
  // Health Connect is available and installed.
  val healthConnectClient = HealthConnectClient.getOrCreate(context)
} else {
  // ...
}
```
注意：部分裝置可能不支援 Health Connect。舉例來說，目前只有搭載 Android 9 (API 級別 28) 以上版本的裝置能夠支援。請先使用 HealthConnectClient.isApiSupported 檢查使用者裝置與 Health Connect 是否相容。如果 isApiSupported() 傳回 false，應用程式就不應要求使用者安裝 Health Connect。
接著，用戶端應用程式必須要求使用者授予權限。使用者隨時可以授予或拒絕用戶端應用程式要求的權限。

HealthConnectClient 會自動管理自身與基礎儲存空間層的連線，並處理傳出要求與傳入回應的所有處理序間通訊 (IPC) 和序列化作業。

步驟 3：宣告權限

宣告應用程式要使用的資料類型權限。

應用程式讀取或寫入的每個資料類型，必須使用資訊清單中的權限進行宣告。如需權限及其對應資料類型的完整清單，請參閱資料類型清單。

從 SDK Alpha 10 以上版本開始，Health Connect 使用標準 Android 權限聲明格式。

<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"/>

如果您使用的是 SDK alpha09 以下版本，請在 res/values/health_permissions.xml 中建立陣列資源。

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.HeartRate.READ</item>
    <item>androidx.health.permission.HeartRate.WRITE</item>
    <item>androidx.health.permission.Steps.READ</item>
    <item>androidx.health.permission.Steps.WRITE</item>
  </array>
</resources>

在資訊清單中新增中繼資料，以說明應用程式使用 Health Connect 的情形。

資訊清單必須提供 <activity>，用於向使用者顯示隱私權政策，說明使用者資料的使用方式和處理方式。您可以新增 <activity>，或是修改現有的範本。

這項活動必須：

(僅適用於 alpha09 以下版本) 參照上述 health_permissions 資源；以及
宣告會處理 ACTION_SHOW_PERMISSIONS_RATIONALE 意圖。當使用者點選 Health Connect 權限對話方塊中的「閱讀隱私權政策」連結時，系統就會將此意圖傳送至應用程式。

<application>
    ...
    <!-- Activity to show rationale of Health Connect permissions -->
    <activity
        android:name=".PermissionsRationaleActivity"
        android:exported="true"
        android:enabled="true">
      <!-- (a) For alpha09 and below, reference permissions resource -->
      <meta-data
          android:name="health_permissions"
          android:resource="@array/health_permissions" />
      <!-- (b) handle intent -->
      <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
      </intent-filter>
    </activity>
    ...
</application>

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

如要顯示權限對話方塊，請先為必要資料類型建構一組權限。確保集合中的權限也如之前所述先進行宣告。

如果是 Alpha10 以上版本：

// build a set of permissions for required data types
val PERMISSIONS =
 setOf(
   HealthPermission.getReadPermission(HeartRateRecord::class),
   HealthPermission.getWritePermission(HeartRateRecord::class),
   HealthPermission.getReadPermission(StepsRecord::class),
   HealthPermission.getWritePermission(StepsRecord::class)
 )

如果是 Alpha09 以下版本：

// build a set of permissions for required data types
val PERMISSIONS =
 setOf(
   HealthPermission.createReadPermission(HeartRateRecord::class),
   HealthPermission.createWritePermission(HeartRateRecord::class),
   HealthPermission.createReadPermission(StepsRecord::class),
   HealthPermission.createWritePermission(StepsRecord::class)
 )

接著，使用 getGrantedPermissions() 查看應用程式是否已具備必要權限。如果沒有，請使用 createRequestPermissionResultContract() 方法要求權限。

// Create the permissions launcher.
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions =
 registerForActivityResult(requestPermissionActivityContract) { granted ->
   if (granted.containsAll(PERMISSIONS)) {
     // Permissions successfully granted
   } else {
     // Lack of required permissions
   }
 }

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
   val granted = healthConnectClient.permissionController.getGrantedPermissions(PERMISSIONS)
   if (granted.containsAll(PERMISSIONS)) {
     // Permissions already granted, proceed with inserting or reading data.
   } else {
     requestPermissions.launch(PERMISSIONS)
   }
}

如果使用者拒絕您的權限要求兩次，您的應用程式將遭到鎖定，且無法再次要求權限。如果應用程式在開發與測試期間遭到鎖定，請開啟 Health Connect 應用程式，並依序選取「allow all」和「remove all」，即可重設權限要求計數。或者，您也可以使用 adb 來清除 Health Connect 套件的快取。

使用者可隨時透過 Health Connect 應用程式授予或撤銷權限。請勿假設授予的權限組合不會變更；您的應用程式應定期檢查授予的權限，並且能夠處理權限意外遺失的情境。

健康資料屬於機密資料，因此為了維護使用者的信任，請僅要求在相關情境下存取資料。請勿要求應用程式未使用的資料。