今日工作：Android Health Connect 接入记录

2026-04-16 15:05

Android Health Connect 接入实战：从 0 到可上线的完整流程

适用人群：Android 健康/运动类应用开发者
目标：把 Health Connect 的接入流程、配置项、关键代码和避坑点一次讲清楚

一、先说结论：为什么要接 Health Connect

Health Connect 是 Android 侧统一的健康数据平台。对开发者来说，核心价值是：

统一 API：不用分别适配多个健康应用的数据接口。
用户可控：权限粒度清晰，用户可随时撤回。
本地存储：数据加密保存在设备端，隐私合规压力更可控。
生态协同：你的应用可以和其他健康应用在同一数据层互通（在用户授权前提下）。

二、版本差异与前置条件

1) 系统版本差异

Android 14+：Health Connect 已并入系统框架，通常无需单独安装 App。
Android 13 及以下：需要用户先安装 Health Connect 应用（Google Play）。

2) 开发和测试前置条件

Android Studio 最新稳定版。
真机 Android 9（API 28）及以上。
设备必须开启锁屏（PIN/图案/密码），否则 Health Connect 可能不可用。

三、项目接入总流程（建议按这个顺序）

添加 SDK 依赖。
在 Manifest 声明包可见性与健康权限。
增加权限用途说明页（隐私政策入口 intent）。
初始化 HealthConnectClient。
实现权限检查 + 动态申请。
接入数据写入（如体重、运动会话）。
接入数据读取（原始记录 + 聚合统计）。
增加后台读取、历史读取能力（按需）。
接入 Differential Changes（差分同步）。
用官方 Toolbox + 真机进行验收测试。

四、核心配置清单（可直接对照）

1) Gradle 依赖

gradle

复制代码

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

建议：实际项目里用最新稳定/推荐版本，避免长期停留在旧 alpha。

2) Manifest：声明 Health Connect 包可见性

xml

复制代码

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

3) Manifest：声明你需要的权限（最小化原则）

xml

复制代码

<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"/>
<uses-permission android:name="android.permission.health.READ_EXERCISE"/>
<uses-permission android:name="android.permission.health.WRITE_EXERCISE"/>
<uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED"/>
<uses-permission android:name="android.permission.health.WRITE_TOTAL_CALORIES_BURNED"/>
<uses-permission android:name="android.permission.health.READ_WEIGHT"/>
<uses-permission android:name="android.permission.health.WRITE_WEIGHT"/>

可选能力（按需声明）：

xml

复制代码

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />
<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

4) Manifest：权限用途说明入口（非常关键）

xml

复制代码

<!-- Android 13 及以下 -->
<intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>

<!-- Android 14+ -->
<intent-filter>
    <action android:name="android.intent.action.VIEW_PERMISSION_USAGE"/>
    <category android:name="android.intent.category.HEALTH_PERMISSIONS"/>
</intent-filter>

这里要落地一个真实可访问的隐私说明页面，讲清楚“用什么数据、为什么用、如何处理、如何删除”。

五、代码接入骨架（建议抽一层 Manager）

1) 初始化客户端

kotlin

复制代码

private val healthConnectClient by lazy { HealthConnectClient.getOrCreate(context) }

2) 权限检查 + 请求 Contract

kotlin

复制代码

suspend fun hasAllPermissions(permissions: Set<String>): Boolean {
    return healthConnectClient.permissionController
        .getGrantedPermissions()
        .containsAll(permissions)
}

fun requestPermissionsActivityContract(): ActivityResultContract<Set<String>, Set<String>> {
    return PermissionController.createRequestPermissionResultContract()
}

3) 体重写入示例（注意时区）

kotlin

复制代码

suspend fun writeWeightInput(weightInput: Double) {
    val time = ZonedDateTime.now().withNano(0)
    val weightRecord = WeightRecord(
        metadata = Metadata.manualEntry(),
        weight = Mass.kilograms(weightInput),
        time = time.toInstant(),
        zoneOffset = time.offset
    )
    healthConnectClient.insertRecords(listOf(weightRecord))
}

4) 读取记录示例

kotlin

复制代码

suspend fun readWeightInputs(start: Instant, end: Instant): List<WeightRecord> {
    val request = ReadRecordsRequest(
        recordType = WeightRecord::class,
        timeRangeFilter = TimeRangeFilter.between(start, end)
    )
    return healthConnectClient.readRecords(request).records
}

5) 聚合读取示例（周平均体重）

kotlin

复制代码

suspend fun computeWeeklyAverage(start: Instant, end: Instant): Mass? {
    val request = AggregateRequest(
        metrics = setOf(WeightRecord.WEIGHT_AVG),
        timeRangeFilter = TimeRangeFilter.between(start, end)
    )
    return healthConnectClient.aggregate(request)[WeightRecord.WEIGHT_AVG]
}

六、进阶能力：后台读取 / 历史读取 / 差分同步

1) 功能可用性检查（不要直接硬调）

kotlin

复制代码

fun isFeatureAvailable(feature: Int): Boolean {
    return healthConnectClient.features.getFeatureStatus(feature) ==
        HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
}

后台读取：FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
历史读取：FEATURE_READ_HEALTH_DATA_HISTORY

2) 差分同步（Differential Changes）

核心思路：

先拿 token（记录某个同步起点）。
下次用 token 拉增量变更（新增/更新/删除）。
持久化新 token。
处理 token 过期（30 天有效期）回退全量或区间同步。

示例骨架：

kotlin

复制代码

suspend fun getChangesToken(): String {
    return healthConnectClient.getChangesToken(
        ChangesTokenRequest(setOf(ExerciseSessionRecord::class))
    )
}

kotlin

复制代码

suspend fun getChanges(token: String): Flow<ChangesMessage> = flow {
    var nextToken = token
    do {
        val response = healthConnectClient.getChanges(nextToken)
        if (response.changesTokenExpired) throw IOException("Changes token expired")
        emit(ChangesMessage.ChangeList(response.changes))
        nextToken = response.nextChangesToken
    } while (response.hasMore)
    emit(ChangesMessage.NoMoreChanges(nextToken))
}

七、必须关注的注意点（项目里最容易踩坑）

权限最小化：只申请你当前页面真正要用的数据类型，否则用户信任下降。
拒绝保护：权限连续拒绝可能导致系统不再弹窗，需要引导用户去设置页手动开启。
时区必填：写记录请带 zoneOffset，否则跨时区展示会错位。
数据来源策略：读取聚合时是否加 dataOriginFilter，决定“只看本应用”还是“融合全来源”。
差分 token 生命周期：30 天会过期，必须有兜底同步策略。
后台能力非全量可用：先 getFeatureStatus 再开放 UI。
真机验证优先：模拟器与不同 ROM 行为可能不一致，尤其权限弹窗与后台任务。
合规文案要可审计：隐私政策和权限用途说明必须与实际采集字段一致。

八、建议的日志与错误处理规范（生产可观测）

你在接入时建议统一按以下规范做：

关键流程打点：权限申请结果、读写请求、聚合请求、差分同步开始/结束。
关键数据日志：请求时间范围、记录数量、来源应用数（避免直接打印敏感值）。
全链路错误日志：SDK 调用异常、权限缺失、token 过期、后台任务失败都要记录错误码和上下文。
统一错误映射：把原始异常映射成业务可理解错误（如“无权限”“数据暂不可用”“请重试”）。

示例（仅示意）：

kotlin

复制代码

try {
    val records = healthConnectClient.readRecords(request).records
    Log.i("HealthConnect", "readWeight success, size=${records.size}, range=$start~$end")
} catch (e: Exception) {
    Log.e("HealthConnect", "readWeight failed, range=$start~$end", e)
    throw e
}