本指南介绍了如何开始在应用中使用 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 SDK(可在 Jetpack 上获取):在您的应用中添加此 SDK,以便使用 Health Connect API。
- API 参考文档:查看适用于 Health Connect API 的 Jetpack 参考文档。
- API 请求开发者声明表单:您可以使用此表单请求对数据类型的读取和写入权限。如需了解详情,请参阅请求对 Health Connect 数据类型的访问权限。
- 可选的 GitHub 代码示例和 Codelab:请参阅 GitHub 代码示例代码库和 Codelab 练习,以便快速上手。
后续步骤
请参阅常见工作流,了解如何在 Health Connect 中执行操作,例如: