Trainingsfunktionen mit Health Connect entwickeln

Wenn Sie in Ihrer App eine Trainingsfunktion entwickeln möchten, können Sie Health Connect für folgende Aufgaben verwenden:

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

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

Übersicht: Umfassenden Tracker für das Training erstellen

So können Sie mit Health Connect eine umfassende Funktion zum Aufzeichnen von Trainings erstellen:

• Berechtigungen basierend auf Health Permissions korrekt implementieren.
• Aufzeichnung von Sitzungen mit ExerciseSessionRecord.
• Trainingsdaten werden während der Sitzung konsistent geschrieben.
• Hintergrundausführung richtig verwalten, um eine kontinuierliche Datenerfassung zu gewährleisten
• Lesen von Sitzungsdaten 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, solltest du Folgendes beachten:

• Health Connect mit der entsprechenden Abhängigkeit einbinden
• Erstellen Sie eine HealthConnectClient-Instanz.
• Prüfe, ob deine App Berechtigungsabläufe zur Laufzeit basierend auf Health Permissions implementiert.
• Wenn in Ihrem Workflow GPS verwendet wird, richten Sie eine Berechtigung zur Standortermittlung und einen Dienst im Vordergrund ein.

Wichtige Konzepte

In Health Connect werden Trainingsdaten anhand einiger wichtiger Komponenten dargestellt. Ein ExerciseSessionRecord dient als zentraler Datensatz für ein Training und enthält Details wie Start- und Endzeiten sowie die Art des Trainings. Während einer Trainingseinheit können verschiedene Datentypen wie HeartRateRecord oder SpeedRecord aufgezeichnet werden. Bei Outdoor-Aktivitäten werden GPS-Daten in ExerciseRoute gespeichert, das mit der entsprechenden Trainingseinheit verknüpft ist.

Trainingseinheiten

ExerciseSessionRecord ist der zentrale Datensatz für Trainingsdaten, der eine einzelne Trainingseinheit darstellt. In jedem Datensatz werden folgende Informationen gespeichert:

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

Ein ExerciseSessionRecord kann auch Trainingsrouten, Runden und Segmente als Teil seiner Daten enthalten. Außerdem können während einer Sitzung andere Datentypen wie HeartRateRecord oder SpeedRecord aufgezeichnet und ihr zugeordnet werden.

Zugehörige Datentypen

Daten zu Trainingseinheiten werden durch einzelne Datensatztypen dargestellt. Häufige Typen sind

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

Eine vollständige Liste der Datentypen finden Sie 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:

• Breiten- und Längengrad
• Optionale Höhe
• Optionale Ausrichtung
• Informationen zur Genauigkeit
• Zeitstempel

Sitzungsrouten verknüpfen

Ein ExerciseRoute enthält die sequenziellen Standortdaten für eine Trainingseinheit. Es wird in Health Connect nicht als unabhängiger Datensatz behandelt. Stattdessen stellen Sie ExerciseRoute-Daten beim Einfügen oder Aktualisieren eines ExerciseSessionRecord bereit.

Überlegungen zur Entwicklung

Apps zur Trainingsaufzeichnung müssen oft über längere Zeiträume hinweg ausgeführt werden, häufig im Hintergrund, wenn der Bildschirm ausgeschaltet ist. Wenn Sie Ihre Trainingsfunktionen entwickeln, ist es wichtig, dass Sie sich überlegen, wie Sie die Hintergrundausführung verwalten und die erforderlichen Berechtigungen für Trainingsdaten anfordern.

Ausführung im Hintergrund

Trainings-Apps werden in der Regel bei ausgeschaltetem Display ausgeführt. In diesem Fall sollten Sie Folgendes verwenden:

• Vordergrunddienste für Standort- und Sensorerfassung
• WorkManager für verzögertes Schreiben oder Synchronisieren
• Batching-Strategien für reguläre Schreibvorgänge

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

Berechtigungen

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

• Trainingssessions: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.
• Distanz:Lese- und Schreibberechtigungen für DistanceRecord.
• Kalorien:Lese- und Schreibberechtigungen für TotalCaloriesBurnedRecord.
• Bewältigte Steigung:Lese- und Schreibberechtigungen für ElevationGainedRecord.
• Schrittfrequenz:Lese- und Schreibberechtigungen für StepsCadenceRecord.
• Strom:Lese- und Schreibberechtigungen für PowerRecord.
• Schritte:Lese- und Schreibberechtigungen für StepsRecord.

Das folgende Beispiel zeigt, wie mehrere Berechtigungen für ein Training angefordert werden, das Daten zu Route, Herzfrequenz, Distanz, Kalorien, Geschwindigkeit und Schritten enthält:

Nachdem Sie eine Client-Instanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen jederzeit die Möglichkeit haben, Berechtigungen zu erteilen oder zu verweigern. Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Die Berechtigungen im Set müssen zuerst in Ihrem 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 Sie nur Berechtigungen für einen einzelnen Datentyp wie die Herzfrequenz anfordern müssen, nehmen Sie nur diesen Datentyp in Ihr 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 Sie Ihrer App die Funktion zur Messung der Herzfrequenz hinzufügen möchten, müssen Sie zuerst Berechtigungen für den Datentyp HeartRateRecord anfordern.

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

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

Zum Lesen der Herzfrequenz müssen Sie die folgenden Berechtigungen anfordern:

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

Trainingseinheit durchführen

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

Sitzung starten

So erstellst du ein neues Training:

1. Eindeutige Sitzungs-ID generieren: Prüfen Sie, ob diese ID stabil ist. Wenn der App-Prozess beendet und neu gestartet wird, müssen Sie die gleiche ID verwenden können, um fragmentierte Sitzungen zu vermeiden.
2. Legen Sie eine metadata.clientRecordId fest, um Duplikate bei Synchronisierungsversuchen zu vermeiden.
3. Schreiben Sie eine ExerciseSessionRecord: Geben Sie die Startzeit an.
4. Datentyp- und GPS-Daten erfassen: Beginnen Sie damit erst, nachdem die Sitzungsaufzeichnung 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(clientRecordId = sessionClientId),
)

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

Trainingsrouten aufzeichnen

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

Wenn Sie eine Trainingsroute aufzeichnen, sollten Sie die Daten in Batches verarbeiten. Das bedeutet, dass Sie nicht jeden einzelnen GPS-Punkt speichern, sobald er erfasst wird, sondern eine Gruppe von Punkten erfassen und sie alle gleichzeitig in einem einzigen Aufruf speichern.

Das ist wichtig, weil jedes Mal, wenn Ihre App Daten in Health Connect liest oder schreibt, ein wenig Akku und Rechenleistung verbraucht werden.

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:

• Eintrag aktualisieren: Ihre App aktualisiert ExerciseSessionRecord mit einem endTime.
• Daten fertigstellen: Optional können Sie Zusammenfassungswerte 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 Zeitraum aufgetreten sind.

Wenn du Trainingsdaten mit einem Backend-Server synchronisieren oder den Datenspeicher deiner App mit Health Connect auf dem neuesten Stand halten musst, 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 das manuelle Nachverfolgen von Änderungen oder das wiederholte Lesen aller Daten. Weitere Informationen findest du unter Daten mit Health Connect synchronisieren.

Sitzungen lesen

Wenn du Trainingseinheiten lesen möchtest, verwende einen ReadRecordsRequest mit ExerciseSessionRecord als Typ. Normalerweise filterst du 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

Obwohl ExerciseRoute-Daten im Rahmen einer Trainingseinheit geschrieben werden, müssen sie separat gelesen werden. Verwenden Sie die Methode getExerciseRoute() mit der ID der Sitzung, um die zugehörigen 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 erfasst wurden, verwende die startTime und endTime der Trainingseinheit, um die Anfrage nach diesem 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:

• Häufig schreiben, wenn das aktive Tracking läuft: Schreiben Sie Daten während des aktiven Trackings, sobald sie verfügbar sind, oder in einem maximalen Intervall von 15 Minuten.
• WorkManager für die Hintergrundsynchronisierung verwenden: Verwenden Sie WorkManager für verzögerte Schreibvorgänge. Wir empfehlen ein 15-Minuten-Intervall, um ein Gleichgewicht zwischen Echtzeitdaten und Akkueffizienz zu erreichen.
• Batchschreibanfragen: 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 Kennzeichnungen für Ihre Sitzungen. Wenn eine Sitzung bearbeitet oder aktualisiert wird, wird sie durch die Verwendung derselben ID nicht als neue, separate Sitzung behandelt.
• Batching für beide Datentypen und Routenpunkte verwenden: Um den Input/Output-Aufwand zu reduzieren und die Akkulaufzeit zu verlängern, 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 Informationen, um eindeutige Datensätze zu identifizieren. Wenn Sie versuchen, einen Datensatz mit einem clientRecordId zu schreiben, der bereits vorhanden ist, ignoriert Health Connect das Duplikat oder aktualisiert den vorhandenen Datensatz, anstatt einen neuen zu erstellen. Wenn Sie eine metadata.clientRecordId festlegen, können Sie Duplikate bei Synchronisierungsversuchen oder Neuinstallationen von Apps am effektivsten verhindern.
  

  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 Datensätze aus Ihrer App vorhanden sind.
• GPS-Genauigkeit prüfen: Filtern Sie GPS-Samples mit geringer Genauigkeit heraus (z. B. Punkte mit einem großen Radius für die horizontale Genauigkeit), bevor Sie in ExerciseRoute schreiben, um sicherzustellen, dass die Karte sauber und professionell aussieht.
• Zeitstempel dürfen sich nicht überschneiden: Achten Sie darauf, dass eine neue Sitzung nicht beginnt, bevor die vorherige endet. Überschneidende Sitzungen 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 Ihre Blutdrucktrends zu überwachen und Statistiken zu erstellen.“
• Pausieren und Fortsetzen unterstützen: Prüfen Sie, ob Ihre App Pausen korrekt verarbeitet. Wenn ein Nutzer eine Pause einlegt, sollten keine Routenpunkte und Datentypen mehr erhoben werden, damit die durchschnittliche Geschwindigkeit und Dauer korrekt bleiben.
• Sitzungen mit langer Laufzeit testen: Überwachen Sie den Akkuverbrauch während mehrstündiger Sitzungen, um zu prüfen, ob das Batching-Intervall und die Sensornutzung den Akku des Geräts nicht zu stark belasten.
• Zeitstempel an Sensorraten anpassen: Passen Sie die Zeitstempel Ihrer Aufzeichnungen an die tatsächliche Häufigkeit Ihrer Sensoren an, um die Datenqualität zu erhalten.

Test

Um die Richtigkeit der Daten und eine hohe Nutzerfreundlichkeit zu gewährleisten, sollten Sie die folgenden Teststrategien anwenden und die offizielle Dokumentation Top-Anwendungsfälle testen lesen.

Tools zur Bestätigung

• Health Connect Toolbox:Mit dieser Begleit-App können Sie Datensätze manuell prüfen, Testdaten löschen und Änderungen an der Datenbank simulieren. So können Sie am besten überprüfen, ob Ihre Datensätze richtig gespeichert werden.
• Unit-Tests mit FakeHealthConnectClient:Mit der Testbibliothek können Sie prüfen, wie Ihre App Grenzfälle wie den Widerruf von Berechtigungen oder API-Ausnahmen ohne physisches Gerät behandelt.

Checkliste für Qualität

Typische Architektur

Eine Trainingsimplementierung umfasst in der Regel:

Fehlerbehebung

Häufige Schritte zur Fehlerbehebung