API Matchmaking

Um guia para a API Matchmaking do Conexão Saúde.

Visão geral

A API Matchmaking permite que seu app descubra outros apps e dispositivos que podem gravar dados de saúde que seu app tem permissão para ler. Isso ajuda os usuários a conectar as fontes de dados favoritas ao seu app com menos dificuldade.

A tela de pareamento descobre apps e dispositivos compatíveis com a Conexão Saúde. Em seguida, ele faz uma referência cruzada entre as permissões de leitura necessárias do app e os recursos de gravação desses apps e dispositivos. A tela mostra apps e dispositivos que declararam, mas ainda não concederam, permissões de gravação para pelo menos um dos tipos de registros especificados que seu app tem permissão para ler.

Antes de começar

Este guia pressupõe que você já tenha configurado a Conexão Saúde no seu app e tenha uma instância de HealthConnectClient disponível.

Configuração da versão Beta

A API Matchmaking está disponível em uma atualização do Conexão Saúde que está sendo lançada gradualmente para dispositivos de produção, com disponibilidade total prevista para o início de junho de 2026. Para testar os recursos de pareamento antes que essa atualização seja disponibilizada para todos, inscreva seu dispositivo de teste no Programa Beta do Android para ter acesso antecipado.

Verificar a disponibilidade da Conexão Saúde

Antes de tentar usar o Conexão Saúde, seu app precisa verificar se ele está disponível no dispositivo do usuário. O app Conexão Saúde pode não estar instalado no dispositivo do usuário ou pode estar desativado.

Use HealthConnectClient.getSdkStatus() para verificar a disponibilidade. Se o app Conexão Saúde não estiver disponível, peça para o usuário instalar ou atualizar o app na Google Play Store.

Verificar a disponibilidade dos recursos

Para determinar se o dispositivo de um usuário é compatível com a correspondência no app Conexão Saúde, verifique a disponibilidade de FEATURE_MATCHMAKING:

if (healthConnectClient
    .features
    .getFeatureStatus(
    HealthConnectFeatures.FEATURE_MATCHMAKING
    ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

// Feature is available
} else {
// Feature isn't available
}

Implementação

O fluxo de matchmaking é iniciado usando um MatchmakingRequest. Essa solicitação define quais tipos de registros você quer que o app colete e permite incluir ou excluir fontes de dados específicas, como apps ou dispositivos:

• recordTypes: um conjunto de classes Record, como StepsRecord::class. Se estiver vazio, o fluxo vai considerar todos os tipos de registros para os quais seu app tem permissões de leitura.
• includedDataSources: um conjunto de objetos DataOrigin para incluir exclusivamente.
• excludedDataSources: um conjunto de objetos DataOrigin a serem excluídos.

Siga estas etapas para integrar a API Matchmaking ao seu aplicativo.

Verificar se é possível fazer uma partida

Antes de mostrar um ponto de entrada de pareamento, use checkIfMatchmakingIsPossible() para determinar se há apps ou dispositivos correspondentes relevantes para os tipos de registros solicitados:

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
    }
}

Recomendamos verificar se a correspondência é possível de forma contínua. Os usuários podem instalar outros apps ou conectar dispositivos com tipos de dados mutuamente compatíveis. Uma abordagem comum é verificar cada vez que o app é iniciado. Se ele retornar true, mostre um ponto de entrada para iniciar o fluxo de pareamento.

Iniciar o fluxo de matchmaking

Se for possível fazer a correspondência, use createMatchmakingIntent() para receber um Intent e iniciar o fluxo da Conexão Saúde. Depois, inicie usando a API Activity Result:

// 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)
}

Ao iniciar essa intent, a Conexão Saúde mostra uma tela em que os usuários podem conferir apps e dispositivos compatíveis e escolher conectá-los para compartilhar dados com seu app.