健康数据共享 Matchmaking API 指南。
概览
借助 Matchmaking 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对象。
请按照以下步骤将 Matchmaking 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，健康数据共享会显示一个界面，用户可以在其中查看兼容的应用和设备，并选择连接这些应用和设备以与您的应用共享数据。