Trainingsfunktionen mit Health Connect entwickeln

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

Wenn du in deiner App eine Trainingsfunktion erstellen möchtest, kannst du Health Connect für Folgendes verwenden:

• Trainingseinheiten schreiben
• Trainingsrouten schreiben
• Trainingsmesswerte wie Herzfrequenz, Geschwindigkeit und Entfernung schreiben
• Trainingsdaten aus anderen Apps lesen

In diesem Leitfaden wird beschrieben, wie du diese Trainingsfunktionen erstellst. Dabei werden Datentypen, die Ausführung im Hintergrund, Berechtigungen, empfohlene Workflows und Best Practices behandelt.

Übersicht: Umfassenden Workout-Tracker erstellen

Mit Health Connect kannst du eine umfassende Workout-Tracking-Funktion erstellen. Folge dazu diesen grundlegenden Schritten:

• Berechtigungen basierend auf Gesundheitsberechtigungen korrekt implementieren.
• Sitzungen mit ExerciseSessionRecord aufzeichnen.
• Trainingsdaten werden während der Trainingseinheit konsistent geschrieben.
• Ordnungsgemäße Verwaltung der Hintergrundausführung, um eine kontinuierliche Datenerfassung zu gewährleisten.
• Lesen von Trainingsdaten für Zusammenfassungen und Analysen nach dem Training.

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

Hinweis

Bevor du Trainingsfunktionen implementierst:

• 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.
• Wenn Ihr Workflow GPS verwendet, richten Sie die Berechtigung zur Standortermittlung und einen Dienst im Vordergrund ein.

Wichtige Konzepte

Health Connect stellt Trainingsdaten mithilfe einiger Kernkomponenten dar. Eine ExerciseSessionRecord dient als zentraler Datensatz für ein Training und enthält Details wie Start- oder Endzeiten und die Art des Trainings. Während einer Sitzung können verschiedene Datentypen wie HeartRateRecord oder SpeedRecord aufgezeichnet werden. Bei Outdoor-Aktivitäten speichert ExerciseRoute GPS-Daten, die mit der entsprechenden Trainingseinheit verknüpft sind.

Trainingseinheiten

ExerciseSessionRecord ist der zentrale Datensatz für Trainingsdaten und stellt eine einzelne Trainingseinheit dar. In jedem Eintrag wird Folgendes gespeichert:

• startTime
• endTime
• exerciseType
• Optionale Sitzungsmetadaten (Titel, Notizen)

Eine ExerciseSessionRecord kann auch Trainingsrouten, Runden und Segmente als Teil ihrer Daten enthalten. Außerdem können während einer Sitzung andere Datentypen wie HeartRateRecord oder SpeedRecord aufgezeichnet und mit ihr verknüpft werden.

Verknüpfte Datentypen

Daten, die mit Trainingseinheiten verknüpft sind, werden durch einzelne Datensatztypen dargestellt. Häufige Typen sind

• HeartRateRecord: Stellt eine Reihe von Herzfrequenzmessungen dar.
• SpeedRecord: Stellt eine Reihe von Geschwindigkeitsmessungen dar.
• DistanceRecord: Gibt die zwischen den Messungen zurückgelegte Strecke an.
• TotalCaloriesBurnedRecord: Gibt die Gesamtzahl der zwischen den Messungen verbrannten Kalorien an.
• ElevationGainedRecord: Gibt den Höhenunterschied zwischen den Messwerten an.
• StepsCadenceRecord: Gibt die Schrittfrequenz zwischen den Messungen an.
• PowerRecord: Gibt die Leistung zwischen Messungen an, was bei Aktivitäten wie Radfahren üblich ist.

Eine vollständige Liste der Datentypen findest du unter Health Connect-Datentypen.

Trainingsrouten

Du kannst eine Route mit Outdoor-Trainings verknüpfen, indem du ExerciseRoute verwendest. Routen bestehen aus sequenziellen ExerciseRoute.Location-Objekten, die jeweils Folgendes enthalten:

• Längen- und Breitengrad
• Optionale Höhe
• Optionaler Peilungswinkel
• Informationen zur Genauigkeit
• Zeitstempel

Sitzungsrouten verknüpfen

Ein ExerciseRoute enthält die sequenziellen Standortdaten für eine Trainingseinheit. Sie werden in Health Connect nicht als eigenständige Datensätze behandelt. Stattdessen geben Sie ExerciseRoute-Daten an, wenn Sie einen ExerciseSessionRecord einfügen oder aktualisieren.

Überlegungen zur Entwicklung

Apps zur Trainingsaufzeichnung müssen oft über längere Zeiträume ausgeführt werden, häufig im Hintergrund, wenn das Display ausgeschaltet ist. Wenn du Trainingsfunktionen entwickelst, ist es wichtig, die Ausführung im Hintergrund zu verwalten und die erforderlichen Berechtigungen für Trainingsdaten anzufordern.

Ausführung im Hintergrund

Trainings-Apps werden häufig bei ausgeschaltetem Display ausgeführt. In diesem Zustand solltest du Folgendes verwenden:

• Dienste im Vordergrund für Standort- und Sensor-Sampling
• WorkManager für verzögertes Schreiben oder Synchronisieren
• Batching-Strategien für das Schreiben regulärer Datensätze

Sorgen Sie für Kontinuität, indem Sie die Sitzungs-ID bei allen Schreibvorgängen einheitlich halten.

Berechtigungen

Ihre App muss die entsprechenden Health Connect-Berechtigungen anfordern, bevor sie Trainingsdaten lesen oder schreiben kann. Zu den gängigen Berechtigungen für Trainings gehören Trainingseinheiten, Trainingsrouten und Messwerte wie Herzfrequenz oder Geschwindigkeit. Das bedeutet:

• Trainingseinheiten:Lese- und Schreibberechtigungen für ExerciseSessionRecord.
• Trainingsrouten:Lese- und Schreibberechtigungen für ExerciseRoute.
• Herzfrequenz:Lese- und Schreibberechtigungen für HeartRateRecord.
• Geschwindigkeit: Lese- und Schreibberechtigungen für SpeedRecord.
• Entfernung:Lese- und Schreibberechtigungen für DistanceRecord.
• Kalorien:Lese- und Schreibberechtigungen für TotalCaloriesBurnedRecord.
• Höhenunterschied:Lese- und Schreibberechtigungen für ElevationGainedRecord.
• Schrittfrequenz:Lese- und Schreibberechtigungen für StepsCadenceRecord.
• Power: Lese- und Schreibberechtigungen für PowerRecord.
• Schritte: Lese- und Schreibberechtigungen für StepsRecord.

Im folgenden Beispiel wird gezeigt, wie Sie mehrere Berechtigungen für eine Trainingseinheit anfordern, die Daten zu Route, Herzfrequenz, Strecke, Kalorien, Geschwindigkeit und Schritten enthält:

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(ExerciseSessionRecord::class),
        HealthPermission.getWritePermission(ExerciseSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(SpeedRecord::class),
        HealthPermission.getWritePermission(SpeedRecord::class),
        HealthPermission.getReadPermission(DistanceRecord::class),
        HealthPermission.getWritePermission(DistanceRecord::class),
        HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::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 du nur Berechtigungen für einen einzelnen Datentyp wie die Herzfrequenz anfordern musst, nimm nur diesen Datentyp in deinen Berechtigungssatz auf:

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

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

Wenn du deiner App die Herzfrequenzfunktion hinzufügen möchtest, musst du zuerst Berechtigungen für den Datentyp HeartRateRecord anfordern.

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

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

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

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

Trainingseinheit implementieren

In diesem Abschnitt wird der empfohlene Workflow zum Aufzeichnen von Trainingsdaten beschrieben.

Sitzung starten

So erstellst du ein neues Training:

1. Generieren Sie eine eindeutige Sitzungs-ID: Prüfen Sie, ob diese ID stabil ist. Wenn der App-Prozess beendet und neu gestartet wird, müssen Sie die Nutzung mit derselben ID fortsetzen können, um fragmentierte Sitzungen zu vermeiden.
2. Legen Sie eine metadata.clientRecordId fest, um Duplikate bei wiederholten Synchronisierungsversuchen zu vermeiden.
3. Schreiben Sie einen ExerciseSessionRecord: Geben Sie die Startzeit an.
4. Datentyp- und GPS-Daten erfassen: Beginne damit erst, nachdem der Sitzungseintrag erfolgreich initialisiert wurde.

Beispiel:

val sessionClientId = UUID.randomUUID().toString()
val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)

val session =   ExerciseSessionRecord(
    startTime = startTime,
    startZoneOffset = zoneOffset,
    endTime = startTime.plusSeconds(3600),
    endZoneOffset = zoneOffset,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata.activelyRecorded(clientRecordId = sessionClientId, device = Device(type = Device.TYPE_PHONE)),
)

healthConnectClient.insertRecords(listOf(session))
HealthConnectManager.kt

Trainingsrouten aufzeichnen

Weitere Informationen zum Lesen von Daten finden Sie unter Rohdaten lesen.

Wenn du eine Trainingsroute aufzeichnest, solltest du deine Daten bündeln. Das bedeutet, dass Sie nicht jeden einzelnen GPS-Punkt speichern, wenn er auftritt, sondern eine Gruppe von Punkten erfassen und alle auf einmal in einem einzigen Aufruf speichern.

Das ist wichtig, weil jedes Mal, wenn deine App Daten in Health Connect liest oder schreibt, ein wenig Akkuleistung und Rechenleistung verbraucht wird.

Der folgende Code zeigt, wie Daten in Batches aufgezeichnet werden:

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

Sitzung beenden

Nachdem Sie die Datenerhebung beendet haben, gilt Folgendes:

• Eintrag aktualisieren: Ihre App aktualisiert ExerciseSessionRecord mit einem endTime.
• Daten finalisieren: Optional können Sie zusammenfassende Werte wie die Gesamtstrecke oder das durchschnittliche Tempo berechnen und als zusätzliche Datensätze schreiben.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

Trainingsdaten lesen

Apps können Trainingseinheiten und die zugehörigen Daten lesen, um Aktivitäten zusammenzufassen, Gesundheitsinformationen bereitzustellen oder Daten mit einem externen Server zu synchronisieren. Sie können beispielsweise einen ExerciseSessionRecord lesen und dann die HeartRateRecord oder DistanceRecord abfragen, die im selben Zeitintervall aufgetreten sind.

Wenn du Trainingsdaten mit einem Backend-Server synchronisieren oder den Datenspeicher deiner App mit Health Connect auf dem neuesten Stand halten möchtest, verwende Änderungsprotokolle. 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.

Sitzungen lesen

Wenn du Trainingseinheiten lesen möchtest, verwende ein ReadRecordsRequest mit dem Typ ExerciseSessionRecord. In der Regel filtern Sie diese nach einem bestimmten Zeitraum.

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

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

Routen lesen

ExerciseRoute-Daten werden zwar im Rahmen einer Trainingseinheit geschrieben, müssen aber separat gelesen werden. Verwenden Sie die Methode getExerciseRoute() mit der ID der Sitzung, um die Routendaten zu lesen:

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

Datentypen lesen

Wenn du bestimmte detaillierte Daten (z. B. die Herzfrequenz) lesen möchtest, die während einer Trainingseinheit aufgezeichnet wurden, verwende die startTime und die endTime der Trainingseinheit, um die Anfrage für diesen Datentyp zu filtern.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.records) {
        for (sample in heartRateRecord.samples) {
            val bpm = sample.beatsPerMinute
        }
    }
}

Best Practices

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

• Während der Aktivitätsaufzeichnung häufig schreiben: Bei der Aktivitätsaufzeichnung sollten Daten geschrieben werden, sobald sie verfügbar sind, oder in einem maximalen Intervall von 15 Minuten.
• WorkManager für Hintergrundsynchronisierungen verwenden: Verwende WorkManager für verzögerte Schreibvorgänge. Ein Intervall von 15 Minuten ist ein guter Kompromiss zwischen Echtzeitdaten und Akkueffizienz.
• Batch-Schreibanfragen: Schreiben Sie nicht jedes einzelne Sensorereignis einzeln. Teilen Sie Ihre Anfragen auf. Health Connect verarbeitet bis zu 1.000 Datensätze pro Schreibanfrage.
• Sitzungs-IDs stabil und eindeutig halten: Verwenden Sie einheitliche Kennungen für Ihre Sitzungen. Wenn eine Trainingseinheit bearbeitet oder aktualisiert wird, wird sie durch die Verwendung derselben ID nicht als neue, separate Trainingseinheit behandelt.
• Batching für Datentypen und Routenpunkte verwenden: Um den Ein-/Ausgabe-Overhead zu reduzieren und den Akku zu schonen, sollten Sie Ihre Datenpunkte in einem einzigen insertRecords-Aufruf gruppieren, anstatt jeden Punkt einzeln zu schreiben.
• 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: Fragen Sie vor der Synchronisierung den Zeitraum ab, um zu sehen, ob bereits Einträge aus Ihrer App vorhanden sind.
• GPS-Genauigkeit validieren: Filtern Sie GPS-Daten mit geringer Genauigkeit heraus (z. B. Punkte mit einem hohen horizontalen Genauigkeitsradius), bevor Sie sie in die ExerciseRoute schreiben, damit die Karte sauber und professionell aussieht.
• Zeitstempel dürfen sich nicht überschneiden: Achten Sie darauf, dass eine neue Sitzung nicht beginnt, bevor die vorherige beendet ist. Sich überschneidende Trainingseinheiten können zu Konflikten in Fitness-Dashboards und Zusammenfassungsberechnungen führen.
• 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.“
• Pausieren und Fortsetzen unterstützen: Prüfen Sie, ob Ihre App Pausen korrekt verarbeitet. Wenn ein Nutzer pausiert, werden keine Routenpunkte und Datentypen mehr erfasst, damit das durchschnittliche Tempo und die Dauer korrekt bleiben.
• Lang andauernde Sitzungen testen: Überwache den Akkuverbrauch während Sitzungen, die mehrere Stunden dauern, um sicherzustellen, dass das Batchintervall und die Sensornutzung den Akku des Geräts nicht zu schnell entladen.
• Zeitstempel an Sensorraten anpassen: Passen Sie die Zeitstempel Ihrer Datensätze an die tatsächliche Frequenz Ihrer Sensoren an, um die Datenqualität zu erhalten.

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 Trainingsimplementierung umfasst in der Regel Folgendes:

Fehlerbehebung

Allgemeine Schritte zur Fehlerbehebung