開始使用

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

開始安裝 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 連線程序的逐步說明:

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

    <!-- Check whether Health Connect is installed or not -->
    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>
    
  2. 請檢查是否已安裝 Health Connect。如果已安裝,請取得 HealthConnectClient 執行個體。

    if (HealthConnectClient.isProviderAvailable(context)) {
      // Health Connect is available and installed.
      val healthConnectClient = HealthConnectClient.getOrCreate(context)
    } else {
      // ...
    }
    
  3. 接著,用戶端應用程式必須要求使用者授予權限。使用者隨時可以授予或拒絕用戶端應用程式要求的權限。

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

步驟 3:宣告權限

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

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

    從 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>
    
  2. 在資訊清單中新增中繼資料,以說明應用程式使用 Health Connect 的情形。

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

    這項活動必須:

    1. (僅適用於 alpha09 以下版本) 參照上述 health_permissions 資源;以及

    2. 宣告會處理 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 應用程式授予或撤銷權限。請勿假設授予的權限組合不會變更;您的應用程式應定期檢查授予的權限,並且能夠處理權限意外遺失的情境。

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