Vitals-Funktionen mit Health Connect entwickeln

Diese Anleitung ist mit Health Connect-Version 1.1.0 oder höher kompatibel.

Wenn du eine App entwickeln möchtest, mit der Nutzer ihre Vitalwerte verwalten können, kannst du Health Connect für Folgendes verwenden:

• Vitalparameter wie Blutdruck, Herzfrequenz und Körpertemperatur aus anderen Apps lesen
• Von deiner App oder verbundenen Geräten aufgezeichnete Vitalparameterdaten schreiben
• Trends beobachten und Gesundheitsstatistiken auf Grundlage von Vitaldaten bereitstellen

In diesem Leitfaden wird beschrieben, wie Sie mit Vitaldaten-Datentypen arbeiten. Es werden Berechtigungen, Lese- und Schreibworkflows sowie Best Practices behandelt.

Übersicht: Umfassenden Vitaldaten-Tracker erstellen

Mit Health Connect kannst du eine umfassende Funktion zum Erfassen von Vitalwerten erstellen. Folge dazu diesen Schritten:

• Anfordern der entsprechenden Berechtigungen für Vitaldatentypen.
• Schreiben von Vitaldaten mithilfe von Datensätzen wie BloodPressureRecord, HeartRateRecord und anderen Vitaldatensätzen.
• Lesen von Vitaldaten zur Anzeige, Analyse oder Synchronisierung.
• Batching für effizientes Schreiben und Lesen von Daten verwenden.

Dieser Workflow ermöglicht die Interoperabilität mit anderen Health Connect-Apps und überprüft den nutzergesteuerten Datenzugriff.

Hinweis

Bevor Sie Vitalfunktionen implementieren:

• Integrieren Sie Health Connect mit der entsprechenden Abhängigkeit.
• Erstellen Sie eine HealthConnectClient-Instanz.
• Prüfen Sie, ob Ihre App Abläufe für Laufzeitberechtigungen basierend auf Gesundheitsberechtigungen implementiert.

Wichtige Konzepte

Vitaldaten in Health Connect werden durch verschiedene Datensatztypen dargestellt, die jeweils einer bestimmten physiologischen Messung entsprechen. Im Gegensatz zu Trainingseinheiten werden Vitaldaten oft als punktuelle oder intervallbasierte Daten aufgezeichnet.

Datentypen für Vitaldaten

Vitaldaten werden durch einzelne Datensatztypen dargestellt. Häufige Typen sind

• BloodPressureRecord: Stellt eine einzelne Blutdruckmessung dar, einschließlich systolischem und diastolischem Druck sowie Körperposition.
• HeartRateRecord: Stellt eine Reihe von Herzfrequenzmessungen dar.
• RestingHeartRateRecord: Stellt eine einzelne Messung der Ruheherzfrequenz dar.
• BodyTemperatureRecord: Stellt einen einzelnen Körpertemperaturmesswert dar, einschließlich des Messorts.
• BloodGlucoseRecord: Stellt einen einzelnen Blutzuckermesswert dar, einschließlich des Bezugs zu einer Mahlzeit und der Probenquelle.
• OxygenSaturationRecord: Stellt einen einzelnen Messwert für die Sauerstoffsättigung des Blutes dar.
• RespiratoryRateRecord: Stellt eine einzelne Atemfrequenzmessung dar.

Eine vollständige Liste der Datentypen finden Sie unter Health Connect-Datentypen.

Überlegungen zur Entwicklung

Vitaldaten können sensibel sein. Apps müssen möglicherweise Daten als Reaktion auf Messungen von Sensoren oder Nutzereingaben schreiben oder Daten von einem Backend synchronisieren. Berechtigungen sind für den Umgang mit Vitaldaten entscheidend.

Berechtigungen

Ihre App muss die entsprechenden Health Connect-Berechtigungen anfordern, bevor sie Vitaldaten lesen oder schreiben kann. Zu den gängigen Berechtigungen für Vitalparameter gehören Blutdruck, Herzfrequenz, Körpertemperatur, Blutzucker, Sauerstoffsättigung und Atemfrequenz. Das bedeutet:

• Blutdruck:Lese- und Schreibberechtigungen für BloodPressureRecord.
• Herzfrequenz:Lese- und Schreibberechtigungen für HeartRateRecord.
• Ruheherzfrequenz:Lese- und Schreibberechtigungen für RestingHeartRateRecord.
• Körpertemperatur:Lese- und Schreibberechtigungen für BodyTemperatureRecord.
• Blutzucker:Lese- und Schreibberechtigungen für BloodGlucoseRecord.
• Sauerstoffsättigung: Lese- und Schreibberechtigungen für OxygenSaturationRecord.
• Atemfrequenz:Lese- und Schreibberechtigungen für RespiratoryRateRecord.

Im folgenden Beispiel wird gezeigt, wie Berechtigungen für Blutdruck, Herzfrequenz und Körpertemperatur angefordert werden:

Nachdem Sie eine Clientinstanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen Berechtigungen jederzeit erteilen oder verweigern können. Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achte darauf, dass die Berechtigungen in der Gruppe zuerst in deinem Android-Manifest deklariert werden.

val permissions =
    setOf(
        HealthPermission.getReadPermission(BloodPressureRecord::class),
        HealthPermission.getWritePermission(BloodPressureRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(BodyTemperatureRecord::class),
        HealthPermission.getWritePermission(BodyTemperatureRecord::class)
    )
HealthConnectManager.kt

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
HealthConnectActivity.kt

Rufen Sie die Funktion checkPermissionsAndRun auf, um Berechtigungen anzufordern:

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

Wenn Sie nur Berechtigungen für einen einzelnen Datentyp wie den Blutdruck anfordern müssen, fügen Sie nur diesen Datentyp in Ihren Berechtigungssatz ein:

Der Zugriff auf Blutdruckdaten wird durch die folgenden Berechtigungen geschützt:

• android.permission.health.READ_BLOOD_PRESSURE
• android.permission.health.WRITE_BLOOD_PRESSURE

Wenn du deiner App eine Blutdruckfunktion hinzufügen möchtest, musst du zuerst Berechtigungen für den Datentyp BloodPressureRecord anfordern.

Hier ist die Berechtigung, die Sie deklarieren müssen, um „Blutdruck“ schreiben zu können:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_BLOOD_PRESSURE" />
...
</application>

Wenn du den Blutdruck auslesen möchtest, musst du die folgenden Berechtigungen anfordern:

<application>
  <uses-permission
android:name="android.permission.health.READ_BLOOD_PRESSURE" />
...
</application>

Vitalparameter schreiben

In diesem Abschnitt wird beschrieben, wie Vitaldaten in Health Connect geschrieben werden. Vitaldaten werden in der Regel als einzelne Datensätze geschrieben. Wenn Sie mehrere Datensätze gleichzeitig schreiben, z. B. beim Synchronisieren von einem Sensor oder Backend, verwenden Sie die Batchverarbeitung.

Beispiel für das Schreiben eines BloodPressureRecord:

suspend fun writeBloodPressureRecord(healthConnectClient: HealthConnectClient) {
    val record = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    healthConnectClient.insertRecords(listOf(record))
}

Batchschreibvorgang

Wenn deine App mehrere Datenpunkte schreiben muss, z. B. beim Synchronisieren von Daten von einem verbundenen Gerät oder einem Backend-Dienst, solltest du Schreibvorgänge im Batch ausführen, um die Effizienz zu verbessern und den Akkuverbrauch zu reduzieren. Health Connect kann bis zu 1.000 Einträge in einer einzelnen Schreibanfrage verarbeiten.

Der folgende Code zeigt, wie mehrere Datensätze gleichzeitig im Batch geschrieben werden:

suspend fun writeBatchRecords(healthConnectClient: HealthConnectClient) {
    val bloodPressureRecord = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    val heartRateRecord = HeartRateRecord(
        startTime = Instant.now().minusSeconds(60),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        samples = listOf(HeartRateRecord.Sample(time = Instant.now().minusSeconds(30), beatsPerMinute = 80))
    )
    healthConnectClient.insertRecords(listOf(bloodPressureRecord, heartRateRecord))
}

Vitalparameterdaten lesen

Apps können Vitaldaten lesen, um Messwerte anzuzeigen, Trends zu analysieren oder Daten mit einem externen Server zu synchronisieren. Wenn Sie Vitaldaten lesen möchten, verwenden Sie einen ReadRecordsRequest mit dem spezifischen Datensatztyp und filtern Sie nach einem Zeitraum.

Beispiel für das Lesen von BloodPressureRecord-Daten:

suspend fun readBloodPressureRecords(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = BloodPressureRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (record in response.records) {
        // Process each blood pressure record
        val systolic = record.systolic
        val diastolic = record.diastolic
    }
}

Wenn du Vitalparameter mit einem Backend-Server synchronisieren oder den Datenspeicher deiner App mit Health Connect auf dem neuesten Stand halten möchtest, verwende ChangeLogs. So können Sie eine Liste der eingefügten, aktualisierten oder gelöschten Datensätze seit einem bestimmten Zeitpunkt abrufen. Das ist effizienter, als Änderungen manuell zu verfolgen oder alle Daten wiederholt zu lesen. Weitere Informationen findest du unter Daten mit Health Connect synchronisieren.

Best Practices

Befolgen Sie diese Richtlinien, um die Zuverlässigkeit der Daten und die Nutzerfreundlichkeit zu verbessern:

• Batch-Schreibanfragen: Um den Ein-/Ausgabe-Overhead zu reduzieren und die Akkulaufzeit zu verlängern, gruppieren Sie Datenpunkte in einem einzigen insertRecords-Aufruf mit Batches von bis zu 1.000 Einträgen, anstatt jeden Punkt einzeln zu schreiben.
• Häufiges Schreiben während des Live-Trackings: Bei häufigen Updates von Sensoren (z. B. Messgeräten zur kontinuierlichen Glukoseüberwachung oder Herzfrequenzmessern) sollten Daten in Batches in Intervallen von bis zu 15 Minuten geschrieben werden, um ein Gleichgewicht zwischen Echtzeit-Updates und Akkueffizienz zu erreichen.
• WorkManager für Hintergrundsynchronisierungen verwenden: Verwenden Sie WorkManager für verzögerte Schreibvorgänge, z. B. zum Synchronisieren von Daten von einem Companion-Gerät oder Backend-Dienst. Versuchen Sie, ein 15-Minuten-Intervall für Batch-Schreibvorgänge zu erreichen.
• Doppelte Daten vermeiden: Client-IDs verwenden: Legen Sie beim Erstellen von Datensätzen eine metadata.clientRecordId fest. Health Connect verwendet diese, um eindeutige Einträge zu identifizieren. Wenn Sie versuchen, einen Eintrag mit einer bereits vorhandenen clientRecordId zu schreiben, ignoriert Health Connect das Duplikat oder aktualisiert den vorhandenen Eintrag, anstatt einen neuen zu erstellen. Das Festlegen einer metadata.clientRecordId ist die effektivste Methode, um Duplikate bei Synchronisierungswiederholungen oder Neuinstallationen von Apps zu vermeiden.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• Vorhandene Daten prüfen: Bevor du Daten synchronisierst, frage Health Connect nach Einträgen im Synchronisierungszeitraum ab, um zu sehen, ob bereits Daten aus deiner App vorhanden sind. So vermeidest du Duplikate oder das Überschreiben neuerer Daten.
• Klare Begründungen für Berechtigungen angeben: Verwenden Sie den Permission.createIntent-Ablauf, um zu erklären, warum Ihre App Zugriff auf Gesundheitsdaten benötigt, z. B.: „Um deine Blutdrucktrends zu beobachten und dir Einblicke zu geben.“
• Zeitstempel mit Messungen abgleichen: Prüfen Sie, ob die Zeitstempel der Datensätze genau widerspiegeln, wann die Messungen vorgenommen wurden. Prüfen Sie bei Intervalldaten wie HeartRateRecord, ob startTime und endTime korrekt sind.

Test

Um die Richtigkeit der Daten und eine hohe Qualität der Nutzererfahrung zu gewährleisten, solltest du die folgenden Teststrategien befolgen und die offizielle Dokumentation Wichtige Anwendungsfälle testen lesen.

Tools zur Überprüfung

• Health Connect Toolbox:Mit dieser Companion-App können Sie Einträge manuell prüfen, Testdaten löschen und Änderungen an der Datenbank simulieren. So können Sie am besten prüfen, ob Ihre Datensätze korrekt gespeichert werden.
• Unittests mit FakeHealthConnectClient: Mit der Testbibliothek können Sie prüfen, wie Ihre App mit Grenzfällen wie dem Widerruf von Berechtigungen oder API-Ausnahmen umgeht, ohne dass ein physisches Gerät erforderlich ist.

Checkliste für Qualität

Typische Architektur

Eine Implementierung von Vitalparametern umfasst in der Regel Folgendes:

Fehlerbehebung

Allgemeine Schritte zur Fehlerbehebung