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 Workout-Tracker erstellen

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

• Berechtigungen basierend auf Gesundheitsberechtigungen korrekt implementieren.
• Aufzeichnungssitzungen 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:

• Health Connect mit der entsprechenden Abhängigkeit einbinden
• Erstellen Sie eine HealthConnectClient-Instanz.
• Prüfen Sie, ob Ihre App Laufzeitberechtigungsabläufe basierend auf Health Permissions implementiert.
• Wenn in Ihrem Workflow GPS verwendet wird, richten Sie eine Standortberechtigung und einen Dienst im Vordergrund ein.

Schlüsselkonzepte

Health Connect stellt Trainingsdaten mit einigen Kernkomponenten dar. Eine ExerciseSessionRecord dient als zentraler Datensatz für ein Training und enthält Details wie Start- und Endzeit sowie den Trainingstyp. 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, der ein einzelnes Training 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.

Verknüpfte 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 Outdoor-Trainings mit einer Route verknüpfen, indem du ExerciseRoute verwendest. Routen bestehen aus sequenziellen ExerciseRoute.Location-Objekten, die jeweils Folgendes enthalten:

• Koordinaten
• Optionale Höhe
• Optionale Ausrichtung
• Informationen zur Genauigkeit
• Zeitstempel

Sitzungsrouten verknüpfen

Ein ExerciseRoute enthält die sequenziellen Standortdaten für ein Training. Sie wird in Health Connect nicht als unabhängiger Datensatz behandelt. Stattdessen geben Sie ExerciseRoute-Daten beim Einfügen oder Aktualisieren eines ExerciseSessionRecord an.

Ü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 häufig 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 Trainings 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.
• Puls: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.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class),
  HealthPermission.getReadPermission(ExerciseRoute::class),
  HealthPermission.getWritePermission(ExerciseRoute::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)
)

Mit getGrantedPermissions können Sie prüfen, ob Ihrer App bereits die erforderlichen Berechtigungen erteilt wurden. Falls nicht, verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Der Bildschirm mit den Health Connect-Berechtigungen wird angezeigt.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss Ihre App jedes Mal prüfen, ob die Berechtigungen vorhanden sind, bevor sie verwendet werden. Außerdem muss sie Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

Rufen Sie die Funktion checkPermissionsAndRun auf, um Berechtigungen anzufordern:

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

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

Wenn Sie die Herzfrequenz auslesen möchten, 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, muss die Verwendung derselben ID fortgesetzt werden 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 sessionId = UUID.randomUUID().toString()
val sessionClientId = UUID.randomUUID().toString()

val session = ExerciseSessionRecord(
    id = sessionId,
    exerciseType = ExerciseType.EXERCISE_TYPE_RUNNING,
    startTime = Instant.now(),
    endTime = null,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))

Trainingsrouten aufzeichnen

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

Wenn Sie eine Trainingsroute aufzeichnen, sollten Sie Ihre Daten in Batches senden. Das bedeutet, dass Sie nicht jeden einzelnen GPS-Punkt speichern, sobald er erfasst wird, sondern eine Gruppe von Punkten erfassen und sie alle auf einmal 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 Gesamtdistanz oder die durchschnittliche Geschwindigkeit berechnen und als zusätzliche Datensätze schreiben.

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

Trainingsdaten lesen

Apps können Trainingssessions 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 Änderungen manuell zu verfolgen oder alle Daten wiederholt zu lesen. Weitere Informationen findest du unter Daten mit Health Connect synchronisieren.

Sitzungen lesen

Verwende zum Lesen von Trainingseinheiten einen ReadRecordsRequest mit ExerciseSessionRecord als Typ. Normalerweise filtern Sie 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 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:

• Schreibhäufigkeit
  • Aktives Tracking(Vordergrund): Bei aktiven Trainings werden Daten geschrieben, sobald sie verfügbar sind, oder in einem maximalen Intervall von 15 Minuten.
  • Hintergrundsynchronisierung:Verwenden Sie WorkManager für verzögerte Schreibvorgänge. Ein Intervall von 15 Minuten ist ein guter Kompromiss zwischen Echtzeitdaten und Akku-Effizienz.
  • Batching:Schreiben Sie nicht jedes einzelne Sensorereignis einzeln. Teilen Sie Ihre Anfragen in kleinere Abschnitte 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 neues, separates Training behandelt.
• Batching für beide Datentypen und Routenpunkte verwenden:Um den Input-/Output-Overhead zu reduzieren und die Akkulaufzeit zu verlängern, sollten Sie Ihre Datenpunkte in einem einzigen insertRecords-Aufruf gruppieren, anstatt jeden Punkt einzeln zu schreiben.

• Duplizierte 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 der App 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:Frage vor der Synchronisierung den Zeitraum ab, um zu sehen, ob bereits Datensätze aus deiner App vorhanden sind.

• GPS-Genauigkeit validieren: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.

• Achten Sie darauf, dass sich Zeitstempel nicht überschneiden:Prüfen Sie, ob eine neue Sitzung 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 Läufe auf einer Karte darzustellen und den Kalorienverbrauch zu berechnen“.

• Unterstützung von Pausieren und Fortsetzen:Prüfen Sie, ob Ihre App Pausen korrekt verarbeitet. Wenn ein Nutzer eine Pause einlegt, werden keine Routenpunkte und Datentypen mehr erhoben, damit die durchschnittliche Geschwindigkeit und die Dauer korrekt bleiben.

• Sitzungen mit langer Laufzeit testen:Überwachen Sie den Akkuverbrauch während Sitzungen, die mehrere Stunden dauern, um zu prüfen, ob Ihr Batching-Intervall und Ihre Sensornutzung den Akku des Geräts nicht zu stark belasten.

• Zeitstempel an Sensorraten anpassen:Passe die Zeitstempel deiner Aufzeichnungen an die tatsächliche Häufigkeit deiner Sensoren an (z. B. 1 Hz für GPS), um die Datenqualität zu erhalten.

Testen

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 Überprüfung

• 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 Folgendes:

Fehlerbehebung

Häufige Schritte zur Fehlerbehebung