開始安裝 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 { // ... }
接著,用戶端應用程式必須要求使用者授予權限。使用者隨時可以授予或拒絕用戶端應用程式要求的權限。
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 應用程式授予或撤銷權限。請勿假設授予的權限組合不會變更;您的應用程式應定期檢查授予的權限,並且能夠處理權限意外遺失的情境。
健康資料屬於機密資料,因此為了維護使用者的信任,請僅要求在相關情境下存取資料。請勿要求應用程式未使用的資料。