Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

开始使用 Health Connect

本指南与健康数据共享版本 1.1.0-alpha12 或更高版本兼容。

本指南介绍如何开始在应用中使用“健康数据共享”。

第 1 步：准备“健康数据共享”应用

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

对健康数据共享的访问权限取决于手机上安装的 Android 版本。以下部分概述了如何处理多个近期的 Android 版本。

Android 14

从 Android 14（API 级别 34）开始，健康数据共享是 Android 框架的一部分。此版本的健康数据共享是一个框架模块。因此，无需进行任何设置。

Android 13 及更低版本

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

如果您已在 Android 13 及更低版本上将应用与“健康数据共享”集成，并且希望在 Android 14 上进行迁移，请参阅从 Android 13 迁移到 Android 14。

打开“健康数据共享”应用

Health Connect 默认不再显示在主屏幕上。您可以通过设置打开健康数据共享，但路径因 Android 版本而异：

在 Android 14 及更高版本中：依次前往设置 > 安全和隐私 > 隐私控制 > Health Connect，或在“设置”中搜索 Health Connect。
在 Android 13 及更低版本上：依次前往设置 > 应用 > Health Connect，或将 Health Connect 添加到您的快捷设置菜单。

第 2 步：将健康数据共享 SDK 添加到您的应用

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

在模块级 build.gradle 文件中添加健康数据共享 SDK 依赖项：

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

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

connect-client 的 1.1.0 版及更高版本需要 compileSdk = 36 和 Android Gradle 插件 (AGP) 8.9.1 版或更高版本。更新模块级 build.gradle 文件中的 compileSdk：

android {
  compileSdk = 36
}

使用 Canary 发布渠道功能

如需使用 Canary 发布渠道中的功能，请在模块级 build.gradle 文件中修改 compileSdk 的版本：

android {
  compileSdkPreview = "CANARY"
}

第 3 步：配置应用

以下部分介绍了如何配置应用以集成到健康数据共享。

查看功能的适用范围

当“健康数据共享”中添加新功能时，用户不一定会更新其“健康数据共享”版本。Feature Availability API 可用于检查用户的设备上是否提供“健康数据共享”中的某项功能，并决定要采取的操作。

用于检查功能可用性的主要函数是 getFeatureStatus()。此方法会返回整数常量 FEATURE_STATUS_AVAILABLE 或 FEATURE_STATUS_UNAVAILABLE：

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}HealthConnectWorker.kt

声明权限

健康与健身数据属于敏感数据。“健康数据共享”为读写操作实现了一层安全保障，从而维护用户信任。

在应用中，根据所需的数据类型在 AndroidManifest.xml 文件中声明读写权限，这些数据类型应与您在 Play 管理中心内声明访问的数据类型一致。

“健康数据共享”会使用标准 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，当用户点击健康数据共享权限界面中的隐私权政策链接时，系统会向应用发送此 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>
...

获取健康数据共享客户端

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

如需获取客户端实例，请先在 Android 清单中声明“健康数据共享”软件包名称。

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

然后，在您的 Activity 中，使用 getSdkStatus 检查是否已安装健康数据共享。如果是，请获取 HealthConnectClient 实例。

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}HealthConnectActivity.kt

第 4 步：向用户请求权限

创建客户端实例后，您的应用需要向用户请求权限。必须允许用户随时授予或拒绝权限。为此，请为所需的数据类型创建一个权限集。先确保此集中的权限已在 Android 清单中声明。

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )HealthConnectManager.kt

使用 getGrantedPermissions 查看您的应用是否已获得所需权限。如不具备，请使用 createRequestPermissionResultContract 请求这些权限。系统会显示“健康数据共享”权限界面。

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}HealthConnectActivity.kt

由于用户可以随时授予或撤消权限，因此您的应用每次在使用权限之前都需要检查权限，并处理权限丢失的情况。

用户入门指导

许多应用都有自定义的新用户引导流程，例如功能教程或征求用户同意。如需让“健康数据共享”能够启动您的初始配置流程，请将以下内容添加到清单中：

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

用户可以直接从 Health Connect 应用（而非您的应用内）发起与您的应用的连接。如果您的应用除了需要获得读取或写入数据的权限之外，还需要进行任何其他互动，请提供新手入门 activity。

请注意，新用户引导 activity 可能会多次启动，例如，如果用户之后撤消了应用的权限，然后重新连接了该应用。

第 5 步：执行操作

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

您的用户可能会使用其他应用将数据同步到健康数据共享，以便您的应用访问。如果用户尚未将这些应用设置为向 Health Connect 写入数据，您可以使用 Matchmaking API 为用户无缝连接这些应用。

写入数据

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

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))HealthConnectManager.kt

然后，使用 insertRecords 写入记录。

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))HealthConnectManager.kt

读取数据

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

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}HealthConnectManager.kt

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

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}HealthConnectManager.kt

视频教程

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

资源

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

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

后续步骤

如需了解如何在健康数据共享中执行操作，请参阅常见工作流，例如：