這份指南說明如何使用健康資料同步 Matchmaking API。
總覽
透過 Matchmaking API，應用程式可以探索其他應用程式和裝置，並寫入應用程式有權讀取的健康資料。這有助於使用者順利將喜愛的資料來源連結至應用程式。
「配對」畫面會找出與「健康資料同步」相容的應用程式和裝置。然後，系統會交叉參照應用程式所需的讀取權限，以及這些應用程式和裝置的寫入功能。畫面上會顯示已聲明但尚未授予寫入權限的應用程式和裝置，這些應用程式和裝置至少有一項指定記錄類型，是您的應用程式獲准讀取的。
事前準備
本指南假設您已在應用程式中設定「健康資料同步」，並有可用的 HealthConnectClient 執行個體。
Beta 版設定
我們將透過 Health Connect 更新，逐步在正式版裝置上推出 Matchmaking API，預計 2026 年 6 月初全面開放使用。如要搶先測試配對功能，請在測試裝置上註冊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)
}
啟動這項意圖後，健康資料同步會顯示畫面，讓使用者查看相容的應用程式和裝置，並選擇連結這些應用程式和裝置，與您的應用程式共用資料。