健康数据共享 对接 API 指南。
概览
借助对接 API，您的应用可以发现其他应用和设备，这些应用和设备可以写入您的应用有权读取的健康数据。这有助于用户以更顺畅的方式将其喜爱的数据源连接到您的应用。
对接界面会发现与 健康数据共享 兼容的应用和设备。然后，它会将您的应用所需的读取权限与这些应用和设备的写入功能进行交叉引用。该界面会显示已声明但尚未授予写入权限的应用和设备，这些应用和设备至少具有您的应用有权读取的指定记录类型之一的写入权限。
准备工作
本指南假定您已在应用中
配置健康数据共享
，并且有一个可用的 HealthConnectClient 实例。
Beta 版设置
对接 API 通过健康数据共享的更新提供，该更新正逐步面向正式版设备发布，预计到 2026 年 6 月初将实现 100% 的可用性。如需在此 更新广泛推出之前测试配对功能，请让您的测试设备加入 Android Beta 版计划以抢先体验。
检查健康数据共享的可用性
在尝试使用健康数据共享之前，您的应用应验证健康数据共享在用户设备上是否可用。健康数据共享可能未安装在用户设备上，或者可能已停用。
使用 HealthConnectClient.getSdkStatus() 检查
可用性。如果健康数据共享不可用，请提示用户从 Google Play 商店安装或更新健康数据共享。
查看功能的适用范围
如需确定用户的设备是否支持健康数据共享上的配对，请检查 FEATURE_MATCHMAKING 的可用性：
if (healthConnectClient
.features
.getFeatureStatus(
HealthConnectFeatures.FEATURE_MATCHMAKING
) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {
// Feature is available
} else {
// Feature isn't available
}
实现
对接流程使用 MatchmakingRequest 启动。此请求定义了您希望应用收集哪些记录类型，并允许您包含或排除特定数据源（例如应用或设备）：
recordTypes：一组Record类，例如StepsRecord::class。如果为空，则流程会考虑您的应用有权读取的所有记录类型。includedDataSources：一组要独占包含的DataOrigin对象。excludedDataSources：一组要排除的DataOrigin对象。
请按照以下步骤将对接 API 集成到您的应用中。
检查是否可以对接
在显示对接入口点之前，请使用 checkIfMatchmakingIsPossible() 确定是否有与所请求记录类型相关的匹配应用或设备：
suspend fun checkMatchmakingPossible(healthConnectClient: HealthConnectClient) {
val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
val response = healthConnectClient.checkIfMatchmakingIsPossible(request)
if (response.isMatchmakingPossible) {
// Relevant apps or devices found. Show entry point to launch flow.
} else {
// Handle case where no new data sources are available
}
}
我们建议您持续检查是否可以对接。
用户日后可能会安装其他应用或连接具有相互兼容数据类型的设备。一种常见的方法是在每次应用启动时进行检查。如果返回 true，则显示用于启动对接流程的入口点。
启动对接流程
如果可以对接，请使用 createMatchmakingIntent() 获取用于启动健康数据共享流程的 Intent
，然后使用 Activity Result
API 启动该流程：
// Create the matchmaking launcher
val matchmakingLauncher = registerForActivityResult(
ActivityResultContracts.StartActivityForResult()
) { result ->
if (result.resultCode == Activity.RESULT_OK) {
// Matchmaking finished successfully.
// User successfully granted at least one permission.
} else {
// User canceled flow or didn't grant permissions.
}
}
fun launchMatchmaking(healthConnectClient: HealthConnectClient) {
val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
val intent = healthConnectClient.createMatchmakingIntent(request)
matchmakingLauncher.launch(intent)
}
通过启动此 intent，健康数据共享 会显示一个界面，用户可以在其中查看兼容的应用和设备，并选择将它们连接起来以与您的应用共享数据。