API Matchmaking

Um guia para a API de matchmaking da Conexão Saúde.

Visão geral

A API de 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 atrito.

A tela de matchmaking descobre apps e dispositivos compatíveis com a Conexão Saúde. Em seguida, ela faz uma referência cruzada das permissões de leitura necessárias do seu app com 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 registro 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.

Verificar a disponibilidade da Conexão Saúde

Antes de tentar usar a Conexão Saúde, seu app precisa verificar se ela está disponível no dispositivo do usuário. A Conexão Saúde pode não estar instalada no dispositivo do usuário ou pode estar desativada.

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

Verificar a disponibilidade dos recursos

Para determinar se o dispositivo de um usuário oferece suporte ao matchmaking na 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 registro você quer que seu 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 considera todos os tipos de registro 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 para excluir.

Siga estas etapas para integrar a API de matchmaking ao seu aplicativo.

Verificar se o matchmaking é possível

Antes de mostrar um ponto de entrada de matchmaking, use checkIfMatchmakingIsPossible() para determinar se há apps ou dispositivos correspondentes relevantes para os tipos de registro 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 o matchmaking é 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 matchmaking.

Iniciar o fluxo de matchmaking

Se o matchmaking for possível, use createMatchmakingIntent() para receber uma Intent para iniciar o fluxo da Conexão Saúde e, em seguida, inicie-o 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 ver apps e dispositivos compatíveis e escolher conectá-los para compartilhar dados com seu app.