开始使用 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 迁移到 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-alpha02"
  ...
}

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

第 3 步:配置应用

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

声明权限

对健康与健身数据的访问属于敏感数据。Health Connect 实现了一个安全层来进行读取和写入操作,从而保持用户信任。

根据所需的数据类型声明对 AndroidManifest.xml 文件的读写权限。填写完此表单后,请务必使用您申请访问权限的一组权限。

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 功能以及实现顺畅集成方面的最佳实践指南:

资源

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

后续步骤

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