Matchmaking API

헬스 커넥트 매치메이킹 API 가이드

개요

매치메이킹 API를 사용하면 앱이 앱에 읽기 권한이 있는 건강 데이터를 쓸 수 있는 다른 앱과 기기를 검색할 수 있습니다. 이를 통해 사용자는 불편함 없이 좋아하는 데이터 소스를 앱에 연결할 수 있습니다.

매치메이킹 화면에서 헬스 커넥트와 호환되는 앱과 기기를 검색합니다. 그런 다음 앱에 필요한 읽기 권한을 해당 앱과 기기의 쓰기 기능과 상호 참조합니다. 화면에는 앱이 읽을 수 있는 지정된 레코드 유형 중 하나 이상의 쓰기 권한을 선언했지만 아직 부여되지 않은 앱과 기기가 표시됩니다.

시작하기 전에

이 가이드에서는 이미 앱에서 헬스 커넥트를 구성했고 HealthConnectClient 인스턴스를 사용할 수 있다고 가정합니다.

베타 설정

매치메이킹 API는 프로덕션 기기에 점진적으로 출시되는 헬스 커넥트 업데이트를 통해 사용할 수 있으며, 2026년 6월 초까지 100% 제공될 예정입니다. 이 업데이트가 정식 출시되기 전에 매치메이킹 기능을 테스트하려면 사전 체험판을 위해 테스트 기기를 Android 베타 프로그램에 등록하세요.

헬스 커넥트 사용 가능 여부 확인

헬스 커넥트를 사용하기 전에 앱에서 사용자의 기기에서 헬스 커넥트를 사용할 수 있는지 확인해야 합니다. 사용자 기기에 헬스 커넥트가 설치되어 있지 않거나 사용 중지되어 있을 수 있습니다.

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: StepsRecord::class와 같은 Record 클래스의 집합입니다. 비어 있으면 흐름에서 앱에 읽기 권한이 있는 모든 레코드 유형을 고려합니다.
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를 가져와 헬스 커넥트 흐름을 실행한 다음 활동 결과 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)
}

이 인텐트를 실행하면 헬스 커넥트에서 호환되는 앱과 기기를 사용자가 확인하고 앱과 데이터를 공유하도록 연결할 수 있는 화면이 표시됩니다.

온보딩 흐름 빌드

헬스 커넥트 홍보