开始

在开始安装 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 处理您的应用发送的所有请求。

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

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

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

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

第 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. 声明应用将使用的数据类型的权限。

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

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

第 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 应用授予或撤消权限。不要假定已授予的权限集不会更改;您的应用应定期检查已授予的权限,并能够应对权限意外丢失的情况。

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