API Matchmaking

Una guida all'API Health Connect Matchmaking.

Panoramica

L'API Matchmaking consente alla tua app di scoprire altre app e altri dispositivi che possono scrivere dati sulla salute che la tua app ha l'autorizzazione a leggere. In questo modo, gli utenti possono connettere le loro origini dati preferite alla tua app in modo più semplice.

La schermata di abbinamento rileva app e dispositivi compatibili con Connessione Salute. Poi esegue il controllo incrociato delle autorizzazioni di lettura richieste dalla tua app con le funzionalità di scrittura di queste app e dispositivi. La schermata mostra le app e i dispositivi che hanno dichiarato, ma non ancora concesso, le autorizzazioni di 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 tu disponga di un'istanza di HealthConnectClient.

Configurazione della versione beta

L'API 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 disponibile per tutti, registra il tuo dispositivo di test al programma beta di Android per l'accesso in anteprima.

Controlla la disponibilità di Connessione Salute

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.

Usa HealthConnectClient.getSdkStatus() per verificare la disponibilità. Se Connessione Salute non è disponibile, chiedi all'utente di installare o aggiornare Connessione Salute dal Google Play Store.

Verificare le funzionalità disponibili

Per determinare se il dispositivo di un utente supporta l'abbinamento 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 i quali la tua app dispone delle 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 Matchmaking nella tua applicazione.

Controllare se è possibile il matchmaking

Prima di mostrare un punto di accesso per il matchmaking, utilizza checkIfMatchmakingIsPossible() per determinare se esistono app o dispositivi di corrispondenza 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 è possibile il matchmaking. In un secondo momento, gli utenti potrebbero installare app aggiuntive 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 entry point per avviare il flusso di matchmaking.

Avviare il flusso di matchmaking

Se è possibile la corrispondenza, 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, Connessione Salute mostra una schermata in cui gli utenti possono vedere app e dispositivi compatibili e scegliere di connetterli per condividere i dati con la tua app.