API Matchmaking

Una guida all'API di matchmaking di Health Connect.

Panoramica

L'API di matchmaking consente alla tua app di scoprire altre app e altri dispositivi che possono scrivere dati sulla salute che la tua app è autorizzata a leggere. In questo modo, gli utenti possono connettere le loro origini dati preferite alla tua app con meno difficoltà.

La schermata di matchmaking rileva le app e i dispositivi compatibili con Health Connect. Quindi, confronta le autorizzazioni di lettura richieste dalla tua app con le funzionalità di scrittura di queste app e di questi dispositivi. La schermata mostra le app e i dispositivi che hanno dichiarato, ma non ancora concesso, le autorizzazioni in scrittura per almeno uno dei tipi di record specificati che la tua app è autorizzata a leggere.

Prima di iniziare

Questa guida presuppone che tu abbia già configurato Health Connect nella tua app e che sia disponibile un'istanza di HealthConnectClient.

Configurazione della versione beta

L'API di matchmaking è disponibile tramite un aggiornamento di Health Connect che viene implementato gradualmente sui dispositivi di produzione, con una disponibilità del 100% prevista entro l'inizio di giugno 2026. Per testare le funzionalità di matchmaking prima che questo aggiornamento sia ampiamente disponibile, registra il tuo dispositivo di test al programma Android Beta per l'accesso in anteprima.

Controlla la disponibilità di Health Connect

Prima di tentare di utilizzare Health Connect, la tua app deve verificare che Health Connect sia disponibile sul dispositivo dell'utente. Health Connect potrebbe non essere installato sul dispositivo dell'utente o potrebbe essere disattivato.

Utilizza HealthConnectClient.getSdkStatus() per verificare la disponibilità. Se Health Connect non è disponibile, chiedi all'utente di installarlo o aggiornarlo dal Google Play Store.

Verificare le funzionalità disponibili

Per determinare se il dispositivo di un utente supporta il matchmaking su Connessione Salute, controlla la disponibilità di FEATURE_MATCHMAKING:

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

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

Implementazione

Il flusso di matchmaking viene avviato utilizzando un MatchmakingRequest. Questa richiesta definisce i tipi di record che vuoi che la tua app raccolga e ti consente di includere o escludere origini dati specifiche, come app o dispositivi:

• recordTypes: un insieme di classi Record come StepsRecord::class. Se è vuoto, il flusso considera tutti i tipi di record per cui la tua app ha le autorizzazioni di lettura.
• includedDataSources: un insieme di oggetti DataOrigin da includere esclusivamente.
• excludedDataSources: un insieme di oggetti DataOrigin da escludere.

Segui questi passaggi per integrare l'API di matchmaking nella tua applicazione.

Verifica se il matchmaking è possibile

Prima di mostrare un punto di ingresso per il matchmaking, utilizza checkIfMatchmakingIsPossible() per determinare se esistono app o dispositivi corrispondenti pertinenti per i tipi di record richiesti:

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

Ti consigliamo di verificare regolarmente se il matchmaking è possibile. Gli utenti potrebbero installare in un secondo momento altre app o connettere dispositivi con tipi di dati reciprocamente compatibili. Un approccio comune consiste nel controllare ogni volta che l'app viene avviata. Se restituisce true, mostra un punto di ingresso per avviare il flusso di matchmaking.

Avvia il flusso di matchmaking

Se la selezione giocatori è possibile, utilizza createMatchmakingIntent() per ottenere un Intent per avviare il flusso di Health Connect, quindi avvialo utilizzando l'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)
}

Avviando questo intent, Health Connect mostra una schermata in cui gli utenti possono visualizzare le app e i dispositivi compatibili e scegliere di connetterli per condividere i dati con la tua app.