开始使用 Health Connect

本指南介绍了如何开始在应用中使用 Health Connect。

第 1 步：准备 Health Connect 应用

健康数据共享应用负责处理您的应用通过健康数据共享 SDK 发送的所有请求。这些请求包括存储数据和管理数据读写访问权限。

能否访问 Health Connect 取决于手机上安装的 Android 版本。以下部分概述了如何处理多个近期的 Android 版本。

Android 14

从 Android 14（API 级别 34）开始，Health Connect 已成为 Android 框架的一部分。此版本的 Health Connect 是一个框架模块。这样一来，您就无需进行任何设置。

Android 13 及更低版本

在 Android 13（API 级别 33）及更低版本中，健康数据共享不是 Android 框架的一部分。因此，您需要从 Google Play 商店安装 Health Connect 应用。

如果您已在 Android 13 及更低版本上将应用与 Health Connect 集成，并且希望在 Android 14 上进行迁移，请参阅从 Android 13 迁移到 Android 14。

打开 Health Connect 应用

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

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

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

Health Connect SDK 负责使用 Health Connect API 发送请求，以便对 Health Connect 应用中的数据存储区执行操作。

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

如需查看最新版本，请参阅 Health Connect 版本。

注意：Health Connect SDK 支持 Android 8（API 级别 26）或更高版本，而 Health Connect 应用仅与 Android 9（API 级别 28）或更高版本兼容。这意味着第三方应用可以支持使用 Android 8 的用户，但只有使用 Android 9 或更高版本的用户才能使用 Health Connect。

第 3 步：配置您的应用

以下部分介绍了如何配置应用以与 Health Connect 集成。

声明权限

访问健康与健身数据属于敏感行为。Health Connect 会实现一层安全机制来保护读写操作，从而赢得用户信任。

根据所需的数据类型声明对 AndroidManifest.xml 文件的读写权限。填写完 [表单]{:.external}后，请务必使用您请求访问的一组权限。

Health Connect 使用标准 Android 权限声明格式。使用 <uses-permission> 标记分配权限。将它们嵌套在 <manifest> 标记中。

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

  <application>
  ...
  </application>
</manifest>

如需查看权限及其对应数据类型的完整列表，请参阅数据类型列表。

显示应用的隐私权政策对话框

您的 Android 清单需要包含一个 activity，用于显示应用的隐私权政策，即应用请求权限的理由，说明如何使用和处理用户数据。

声明此 activity 以处理 ACTION_SHOW_PERMISSIONS_RATIONALE intent，当用户点击 Health Connect 权限界面中的隐私权政策链接时，系统会将此 intent 发送到应用。

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

获取 Health Connect 客户端

HealthConnectClient 是 Health Connect API 的入口点。它允许应用使用 Health Connect 应用中的数据存储区。它会自动管理它与底层存储层的关联，并处理传出请求和传入响应的所有 IPC 和序列化。

如需获取客户端实例，请先在 Android 清单中声明 Health Connect 软件包名称。

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

然后，在 activity 中，使用 getSdkStatus 检查是否已安装 Health Connect。如果是，请获取 HealthConnectClient 实例。

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // Optionally redirect to package installer to find a provider, for example:
  val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
  context.startActivity(
    Intent(Intent.ACTION_VIEW).apply {
      setPackage("com.android.vending")
      data = Uri.parse(uriString)
      putExtra("overlay", true)
      putExtra("callerId", context.packageName)
    }
  )
  return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

第 4 步：向用户请求权限

创建客户端实例后，您的应用需要向用户请求权限。必须允许用户随时授予或拒绝权限。

为此，请为所需的数据类型创建一组权限。请先确保此集中的权限已在 Android 清单中声明。

// Create 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)
)

使用 getGrantedPermissions 查看您的应用是否已获得所需的权限。如不具备，请使用 createRequestPermissionResultContract 请求这些权限。系统随即会显示 Health Connect 权限屏幕。

// 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()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

请勿假定权限是恒定的，因为用户可以随时授予或撤消权限。您的应用需要定期检查已授予的权限，并应对权限丢失的情况。

第 5 步：执行操作

现在，一切都已设置完毕，在您的应用中执行读写操作。

写入数据

将您的数据构建成一个记录。查看 Health Connect 中支持的数据类型列表。

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

然后，使用 insertRecords 写入记录。

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

读取数据

您可以使用 readRecords 逐个读取数据。

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

您还可以使用 aggregate 以汇总方式读取数据。

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

重要提示： Health Connect 可以读取首次授予权限前最多 30 天的数据。不过，如果用户删除您的应用，权限历史记录将会丢失。如果用户重新安装您的应用并再次授予权限，Health Connect 便可读取从获授该权限的新日期最多回推 30 天的相关数据。

视频教程

观看以下视频，详细了解 Health Connect 功能以及实现顺畅集成方面的最佳实践指南：

• 在 Health Connect 中管理权限
• 在 Health Connect 中读取和写入
• 实现出色 Health Connect 集成的技巧

资源

请查看以下资源，它们有助于之后的开发工作。

• Health Connect SDK（可在 Jetpack 上获取）：在您的应用中添加此 SDK，以使用 Health Connect API。
• API 参考文档：查看适用于 Health Connect API 的 Jetpack 参考文档。
• 声明使用数据类型：在 Play 管理中心内，声明对应用读取和写入的 Health Connect 数据类型的访问权限。
• 可选的 GitHub 代码示例和 Codelab：请参阅 GitHub 代码示例库和 Codelab 练习，以便快速上手。

注意：如果您因为应用需要新的数据类型而申请另一项请求，则需要同时包含新的数据类型和现有的数据类型，并排除您不再需要的任何数据类型。如果您只需要移除对特定数据类型的访问权限，请添加所有现有数据类型，但排除您不再需要的数据类型。

后续步骤

请参阅常见工作流，了解如何在 Health Connect 中执行操作，例如：

• 写入数据
• 读取原始数据
• 读取汇总数据