开始使用 Health Connect

本指南介绍如何在您的应用程序中开始使用 Health Connect。

步骤 1：准备 Health Connect 应用程序

Health Connect 应用程序负责处理您的应用程序通过 Health Connect SDK 发送的所有请求。这些请求包括存储数据以及管理其读写访问权限。

对 Health Connect 的访问权限取决于手机上安装的 Android 版本。以下部分概述了如何处理几个最近版本的 Android。

Android 14

从 Android 14（API 级别 34）开始，Health Connect 是 Android 框架的一部分。此版本的 Health Connect 是一个框架模块。这样，就不需要任何设置。

Android 13 及更低版本

在 Android 13（API 级别 33）和更低版本上，Health Connect 不属于 Android 框架。因此，您需要从 Google Play 商店安装 Health Connect 应用程序。

如果您已在 Android 13 及更低版本上将您的应用程序与 Health Connect 集成，并且想要在 Android 14 上进行迁移，请参考 从 Android 13 迁移到 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-alpha02"
  ...
}

参考 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 意图，该意图在用户点击 Health Connect 权限屏幕中的 **隐私政策** 链接时发送到应用。

...
<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 功能的更多信息，以及实现平滑集成的最佳实践指南。

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

资源

查看以下资源，它们可以帮助您在以后进行开发。

• Health Connect SDK（可在 Jetpack 上获取）：在您的应用中包含此 SDK 以使用 Health Connect API。
• API 参考：查看 Jetpack 参考，了解有关 Health Connect API 的信息。
• 声明数据类型的使用情况：在 Play Console 中，声明访问您的应用从中读取和写入的 Health Connect 数据类型。
• 可选的 Github 代码示例和 Codelab：查看 Github 代码示例 存储库 和 Codelab 练习，以帮助您入门。

后续步骤

查看 **常见工作流程**，了解如何在 Health Connect 中执行操作，例如

• 写入数据
• 读取原始数据
• 读取聚合数据