Matchmaking API

Anleitung zur Health Connect Matchmaking API

Übersicht

Mit der Matchmaking API kann deine App andere Apps und Geräte finden, die Gesundheitsdaten schreiben können, die deine App lesen darf. So können Nutzer ihre bevorzugten Datenquellen einfacher mit deiner App verbinden.

Auf dem Matchmaking-Bildschirm werden Health Connect-kompatible Apps und Geräte gefunden. Anschließend werden die erforderlichen Leseberechtigungen deiner App mit den Schreibfunktionen dieser Apps und Geräte verglichen. Auf dem Bildschirm werden Apps und Geräte angezeigt, die Schreibberechtigungen für mindestens einen der angegebenen Datensatztypen deklariert, aber noch nicht gewährt haben, die deine App lesen darf.

Hinweis

In dieser Anleitung wird davon ausgegangen, dass du Health Connect bereits in deiner App konfiguriert hast und eine Instanz von HealthConnectClient verfügbar ist.

Beta-Einrichtung

Die Matchmaking API ist über ein Update für Health Connect verfügbar, das nach und nach auf Produktionsgeräten eingeführt wird. Die vollständige Verfügbarkeit wird voraussichtlich Anfang Juni 2026 erreicht. Wenn du die Matchmaking-Funktionen testen möchtest, bevor dieses Update allgemein verfügbar ist, registriere dein Testgerät für das Android-Betaprogramm, um Vorabzugriff zu erhalten.

Verfügbarkeit von Health Connect prüfen

Bevor deine App versucht, Health Connect zu verwenden, sollte sie prüfen, ob Health Connect auf dem Gerät des Nutzers verfügbar ist. Health Connect ist möglicherweise nicht auf dem Gerät des Nutzers installiert oder deaktiviert.

Verwende HealthConnectClient.getSdkStatus(), um die Verfügbarkeit zu prüfen. Wenn Health Connect nicht verfügbar ist, fordere den Nutzer auf, Health Connect im Google Play Store zu installieren oder zu aktualisieren.

Verfügbarkeit von Funktionen überprüfen

Um herauszufinden, ob das Gerät eines Nutzers Matchmaking in Health Connect unterstützt, prüfe, ob FEATURE_MATCHMAKING verfügbar ist:

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

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

Implementierung

Der Matchmaking-Ablauf wird mit einer MatchmakingRequest gestartet. In dieser Anfrage wird festgelegt, welche Datensatztypen deine App erfassen soll. Außerdem kannst du bestimmte Datenquellen wie Apps oder Geräte ein- oder ausschließen:

• recordTypes: Eine Reihe von Record-Klassen wie StepsRecord::class. Wenn das Feld leer ist, werden alle Datensatztypen berücksichtigt, für die deine App Leseberechtigungen hat.
• includedDataSources: Eine Reihe von DataOrigin-Objekten, die ausschließlich eingeschlossen werden sollen.
• excludedDataSources: Eine Reihe von DataOrigin-Objekten, die ausgeschlossen werden sollen.

Führe die folgenden Schritte aus, um die Matchmaking API in deine Anwendung einzubinden.

Prüfen, ob Matchmaking möglich ist

Bevor du einen Matchmaking-Einstiegspunkt anzeigst, prüfe mit checkIfMatchmakingIsPossible(), ob es relevante übereinstimmende Apps oder Geräte für die angeforderten Datensatztypen gibt:

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

Wir empfehlen, regelmäßig zu prüfen, ob Matchmaking möglich ist. Nutzer installieren möglicherweise später zusätzliche Apps oder verbinden Geräte mit kompatiblen Datentypen. Ein gängiger Ansatz ist, die Prüfung bei jedem Start deiner App durchzuführen. Wenn true zurückgegeben wird, zeige einen Einstiegspunkt an, um den Matchmaking-Ablauf zu starten.

Matchmaking-Ablauf starten

Wenn Matchmaking möglich ist, verwende createMatchmakingIntent(), um eine Intent zum Starten des Health Connect-Ablaufs abzurufen. Starte sie dann mit der Activity Result API:

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

Wenn du diese Intent startest, zeigt Health Connect einen Bildschirm an, auf dem Nutzer kompatible Apps und Geräte sehen und sie verbinden können, um Daten mit deiner App zu teilen.