API de Matchmaking

Una guía para la API de Health Connect Matchmaking.

Descripción general

La API de Matchmaking permite que tu app descubra otras apps y dispositivos que pueden escribir datos de salud que tu app tiene permiso para leer. Esto ayuda a los usuarios a conectar sus fuentes de datos favoritas a tu app con menos fricción.

La pantalla de Matchmaking descubre apps y dispositivos compatibles con Health Connect. Luego, hace una referencia cruzada de los permisos de lectura obligatorios de tu app con las capacidades de escritura de esas apps y dispositivos. La pantalla muestra las apps y los dispositivos que declararon, pero aún no otorgaron, permisos de escritura para al menos uno de los tipos de registros especificados que tu app tiene permiso para leer.

Antes de comenzar

En esta guía, se supone que ya configuraste Health Connect en tu app y que tienes una instancia de HealthConnectClient disponible.

Configuración de la versión beta

La API de Matchmaking está disponible a través de una actualización de Health Connect que se está lanzando gradualmente a los dispositivos de producción, con una disponibilidad del 100% prevista para principios de junio de 2026. Para probar las funciones de matchmaking antes de que esta actualización esté disponible de forma generalizada, inscribe tu dispositivo de prueba en el programa Android Beta para obtener acceso anticipado.

Verifica la disponibilidad de Health Connect

Antes de intentar usar Health Connect, tu app debe verificar que esté disponible en el dispositivo del usuario. Es posible que Health Connect no esté instalado en el dispositivo del usuario o que esté inhabilitado.

Usa HealthConnectClient.getSdkStatus() para verificar la disponibilidad. Si Health Connect no está disponible, pídele al usuario que lo instale o actualice desde Google Play Store.

Revisa la disponibilidad de las funciones

Para determinar si el dispositivo de un usuario admite el matchmaking en Health Connect, verifica la disponibilidad de FEATURE_MATCHMAKING:

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

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

Implementación

El flujo de matchmaking se inicia con un MatchmakingRequest. Esta solicitud define qué tipos de registros deseas que recopile tu app y te permite incluir o excluir fuentes de datos específicas, como apps o dispositivos:

• recordTypes: Un conjunto de clases Record, como StepsRecord::class. Si está vacío, el flujo considera todos los tipos de registros para los que tu app tiene permisos de lectura.
• includedDataSources: Un conjunto de objetos DataOrigin para incluir de forma exclusiva.
• excludedDataSources: Un conjunto de objetos DataOrigin para excluir.

Sigue estos pasos para integrar la API de Matchmaking en tu aplicación.

Verifica si es posible el matchmaking

Antes de mostrar un punto de entrada de matchmaking, usa checkIfMatchmakingIsPossible() para determinar si hay apps o dispositivos coincidentes relevantes para los 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
    }
}

Te recomendamos que verifiques si el matchmaking es posible de forma continua. Es posible que los usuarios instalen apps adicionales o conecten dispositivos con tipos de datos mutuamente compatibles más adelante. Un enfoque común es verificar cada vez que se inicia la app. Si devuelve true, muestra un punto de entrada para iniciar el flujo de creación de partidas.

Inicia el flujo de Matchmaking

Si es posible el matchmaking, usa createMatchmakingIntent() para obtener un Intent para iniciar el flujo de Health Connect y, luego, iniciarlo con la API de 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)
}

Al iniciar este intent, Health Connect muestra una pantalla en la que los usuarios pueden ver apps y dispositivos compatibles, y elegir conectarlos para compartir datos con tu app.