开始

在开始安装 Health Connect 之前，请参阅以下资源。

资源

• Health Connect SDK（可在 Jetpack 上获取）。在您的应用中添加此 SDK，以使用 Health Connect API。
• API 参考文档。如需了解 Health Connect API，请参阅 Jetpack 参考文档。
• API 请求开发者声明表单。用于请求对数据类型的读取和/或写入权限的表单。
• GitHub 代码示例和 Codelab（可选）。请参阅 GitHub 代码示例代码库和 Codelab，以便快速上手。

请按照下面简单快捷的步骤操作，与 Health Connect 集成：

第 0 步：安装 Health Connect

在您的设备中，通过 Google Play 商店安装 Health Connect by Android。它将使用 Health Connect SDK 处理您的应用发送的所有请求。

注意：Health Connect 默认不再显示在主屏幕上。如需打开 Health Connect，请依次前往设置 > 应用 > Health Connect或将 Health Connect 添加到您的快捷设置菜单。

注意：Health Connect 要求用户使用 PIN 码、图案或密码启用屏幕锁定，以便在设备锁定时保护存储在 Health Connect 中的健康数据免受恶意方的入侵。如需设置屏幕锁定，请依次前往设置 > 安全 > 屏幕锁定。

第 1 步：将 Health Connect SDK 添加到您的应用

在模块的 build.gradle 文件中添加 Health Connect SDK 的依赖项：

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

在发布版本中查找最新版本。

注意：Health Connect SDK 要求客户端应用在 API 级别 26 (minSdkVersion=26) 或更高级别上运行。

第 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 {
     // ...
   }
   

   注意：Health Connect 可能不适用于某些设备。例如，目前仅适用于搭载 Android 9（API 级别 28）或更高版本的设备。先使用 HealthConnectClient.isApiSupported 检查用户的设备是否与 Health Connect 兼容。 如果 isApiSupported() 返回 false，则应用不应要求用户安装 Health Connect。

3. 然后，客户端应用必须向用户请求权限。用户可以随时授予或拒绝对客户端应用的访问权限。

HealthConnectClient 会自动管理它与底层存储层的关联，并处理传出请求和传入响应的所有 IPC 和序列化。

第 3 步：声明权限

1. 声明应用将使用的数据类型的权限。

   您的应用读取或写入的每种数据类型都需要使用清单中的权限进行声明。如需查看权限及其对应数据类型的完整列表，请参阅数据类型列表。

   如需创建声明，请在 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>。

   此 activity 必须：(a) 引用上述 health_permissions 资源；并 (b) 声明它将处理 ACTION_SHOW_PERMISSIONS_RATIONALE intent。当用户点击 Health Connect 权限对话框中的“阅读隐私权政策”链接时，系统会向应用发送此 intent。

   <application>
       ...
       <!-- Activity to show rationale of Health Connect permissions -->
       <activity
           android:name=".PermissionsRationaleActivity"
           android:exported="true"
           android:enabled="true">
         <!-- (a) 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>
   

注意：当启用公开 ACTION_SHOW_PERMISSIONS_RATIONALE 的 activity 后，您的应用将作为可用应用显示在 Health Connect 中。如需在 Health Connect 集成就绪之前隐藏集成情况，请先在清单中使用 android:enabled="false" 停用此 activity。准备好开启后，可以使用 PackageManager.setComponentEnabledSetting 对其进行动态启用。

第 4 步：向用户请求权限

如需显示权限对话框，请先为所需的数据类型构建一组权限。确保 res/values/health_permissions.xml 中也声明了该组中的权限，如前所述。

// 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 应用，然后依次选择全部允许和全部移除。或者，使用 adb 清除 Health Connect 软件包的缓存。

用户可以随时使用 Health Connect 应用授予或撤消权限。不要假定已授予的权限集不会更改；您的应用应定期检查已授予的权限，并能够应对权限意外丢失的情况。

健康数据属于敏感数据，因此为了维持用户信任，请仅请在用户执行相关操作时提出权限请求。请勿请求您的应用并不使用的数据。

注意：如需查看有关如何在 Health Connect 中执行 CRUD 操作的更多示例（例如写入步数数据、营养数据等），请参阅常见工作流。