Daten schreiben

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha12 kompatibel.

In diesem Leitfaden wird beschrieben, wie Daten in Health Connect geschrieben oder aktualisiert werden.

Nullwerte verarbeiten

Einige Datentypen wie Schritte, Entfernung oder Kalorien haben möglicherweise den Wert 0. Schreibe nur dann Nullwerte, wenn dies der tatsächlichen Inaktivität entspricht, während der Nutzer das Gerät getragen hat. Schreibe keine Nullwerte, wenn das Gerät nicht getragen wurde, Daten fehlen oder der Akku leer ist. Lassen Sie den Datensatz in solchen Fällen weg, um irreführende Daten zu vermeiden.

Datenstruktur einrichten

Bevor wir Daten schreiben können, müssen wir zuerst die Datensätze einrichten. Für mehr als 50 Datentypen gibt es jeweils eigene Strukturen. Weitere Informationen zu den verfügbaren Datentypen finden Sie in der Jetpack-Referenz.

Grundlegende Datensätze

Der Datentyp Schritte in Health Connect erfasst die Anzahl der Schritte, die ein Nutzer zwischen den Messungen zurückgelegt hat. Schrittzahlen sind eine gängige Messung auf Gesundheits-, Fitness- und Wellnessplattformen.

Im folgenden Beispiel wird gezeigt, wie Schrittzählerdaten festgelegt werden:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)

Aufzeichnungen mit Maßeinheiten

In Health Connect können Werte zusammen mit ihren Maßeinheiten gespeichert werden, um die Genauigkeit zu gewährleisten. Ein Beispiel ist der Datentyp Nutrition, der sehr umfangreich ist. Sie umfasst eine Vielzahl optionaler Nährwertfelder, die von Gesamtkohlenhydraten bis hin zu Vitaminen reichen. Jeder Datenpunkt steht für die Nährstoffe, die möglicherweise im Rahmen einer Mahlzeit oder eines Lebensmittels aufgenommen wurden.

Bei diesem Datentyp werden alle Nährstoffe in Einheiten von Mass angegeben, während energy in Einheiten von Energy angegeben wird.

Das folgende Beispiel zeigt, wie Ernährungsdaten für einen Nutzer festgelegt werden, der eine Banane gegessen hat:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(1))

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        device = Device(type = Device.TYPE_PHONE)
    )
)

Datensätze mit Seriendaten

In Health Connect kann eine Liste von Seriendaten gespeichert werden. Ein Beispiel ist der Datentyp Herzfrequenz, der eine Reihe von Herzschlagsamples erfasst, die zwischen Messungen erkannt wurden.

In diesem Datentyp wird der Parameter samples durch eine Liste von Herzfrequenzmessungen dargestellt. Jede Stichprobe enthält einen beatsPerMinute-Wert und einen time-Wert.

Im folgenden Beispiel wird gezeigt, wie du Daten für die Herzfrequenzserie festlegst:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(5))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    },
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))

Berechtigungen vom Nutzer anfordern

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. Achten Sie darauf, dass die Berechtigungen im Set zuerst in Ihrem Android-Manifest deklariert werden.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::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. Dadurch wird der Bildschirm mit den Health Connect-Berechtigungen 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 regelmäßig prüfen, welche Berechtigungen erteilt wurden, und Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

Daten schreiben

Einer der häufigsten Workflows in Health Connect ist das Schreiben von Daten. Verwenden Sie insertRecords, um Einträge hinzuzufügen.

Das folgende Beispiel zeigt, wie Daten zum Einfügen von Schrittzahlen geschrieben werden:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(5))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            )
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Daten aktualisieren

Wenn Sie einen oder mehrere Datensätze ändern müssen, insbesondere wenn Sie Ihren App-Datenspeicher mit Daten aus Health Connect synchronisieren müssen, können Sie Ihre Daten aktualisieren. Es gibt zwei Möglichkeiten, vorhandene Daten zu aktualisieren. Welche Sie verwenden, hängt von der Kennung ab, mit der Datensätze gesucht werden.

Metadaten

Es empfiehlt sich, zuerst die Klasse Metadata zu untersuchen, da sie für die Aktualisierung von Daten erforderlich ist. Beim Erstellen hat jedes Record in Health Connect ein Feld metadata. Die folgenden Eigenschaften sind für die Synchronisierung relevant:

Nach Zeitbereich aktualisieren

Bereiten Sie zuerst die erforderlichen Datensätze vor, um Daten zu aktualisieren. Nehmen Sie bei Bedarf Änderungen an den Einträgen vor. Rufen Sie dann updateRecords auf, um die Änderungen vorzunehmen.

Im folgenden Beispiel wird gezeigt, wie Daten aktualisiert werden. Dazu werden die Zeitzonen-Offsetwerte jedes Datensatzes in PST angepasst.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class, timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime, prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        healthConnectClient.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Upsert über die Client-Datensatz-ID

Wenn Sie die optionalen Werte „Client Record ID“ (Clientdatensatz-ID) und „Client Record Version“ (Clientdatensatz-Version) verwenden, empfehlen wir, insertRecords anstelle von updateRecords zu verwenden.

Die Funktion insertRecords kann Daten einfügen oder aktualisieren. Wenn die Daten in Health Connect anhand der angegebenen Client Record-IDs vorhanden sind, werden sie überschrieben. Andernfalls werden sie als neue Daten geschrieben. Dieses Szenario ist immer dann nützlich, wenn Sie Daten aus dem Datenspeicher Ihrer App mit Health Connect synchronisieren müssen.

Das folgende Beispiel zeigt, wie Sie einen Upsert für Daten ausführen, die aus dem App-Datenspeicher abgerufen wurden:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        metadata = Metadata.autoRecorded(
            clientRecordId = "Your client record ID",
            device = Device(type = Device.TYPE_WATCH)
        ),
        // Assign more parameters for this record
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Danach können Sie diese Funktionen in Ihrem Hauptthread aufrufen.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Wertprüfung in der Clientdatensatzversion

Wenn Ihr Prozess zum Einfügen und Aktualisieren von Daten die Client Record Version umfasst, führt Health Connect Vergleichsprüfungen in den clientRecordVersion-Werten durch. Wenn die Version aus den eingefügten Daten höher ist als die Version aus den vorhandenen Daten, wird der Upsert-Vorgang ausgeführt. Andernfalls wird die Änderung ignoriert und der Wert bleibt gleich.

Wenn Sie die Versionsverwaltung in Ihre Daten aufnehmen möchten, müssen Sie Metadata.clientRecordVersion mit einem Long-Wert basierend auf Ihrer Versionsverwaltungslogik angeben.

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 100L,
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)

Bei Upserts wird version nicht automatisch inkrementiert, wenn Änderungen vorgenommen werden. So wird verhindert, dass Daten unerwartet überschrieben werden. Sie müssen also manuell einen höheren Wert angeben.

Best Practices für das Schreiben von Daten

Apps dürfen nur eigene Daten in Health Connect schreiben.

Wenn Daten in Ihre App aus einer anderen App importiert wurden, ist die andere App dafür verantwortlich, ihre eigenen Daten in Health Connect zu schreiben.

Es empfiehlt sich außerdem, eine Logik zu implementieren, die Schreibausnahmen wie Daten außerhalb des zulässigen Bereichs oder einen internen Systemfehler behandelt. Sie können Ihre Backoff- und Wiederholungsstrategien auf einen Mechanismus zur Jobplanung anwenden. Wenn das Schreiben in Health Connect letztendlich nicht erfolgreich ist, muss Ihre App den Exportvorgang fortsetzen können. Vergessen Sie nicht, Fehler zu protokollieren und zu melden, um die Diagnose zu erleichtern.

Beim Erfassen von Daten gibt es je nach Art der Datenerfassung in Ihrer App einige Empfehlungen, die Sie befolgen können.

Umgang mit Zeitzonen

Vermeiden Sie beim Schreiben zeitbasierter Datensätze, Offsets standardmäßig auf zoneOffset.UTC festzulegen, da dies zu ungenauen Zeitstempeln führen kann, wenn sich Nutzer in anderen Zeitzonen befinden. Berechnen Sie den Versatz stattdessen anhand des tatsächlichen Standorts des Geräts. Sie können die Zeitzone des Geräts mit ZoneId.systemDefault() abrufen.

val endTime = Instant.now()
val startTime = endTime.minus(java.time.Duration.ofDays(1))
val stepsRecords = mutableListOf<StepsRecord>()
var sampleTime = startTime
val minutesBetweenSamples = 15L
while (sampleTime < endTime) {
    // Get the default ZoneId then convert it to an offset
    val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(sampleTime)
    stepsRecords += StepsRecord(
        startTime = sampleTime.minus(java.time.Duration.ofMinutes(minutesBetweenSamples)),
        startZoneOffset = zoneOffset,
        endTime = sampleTime,
        endZoneOffset = zoneOffset,
        count = Random.nextLong(1, 100),
        metadata = Metadata.unknownRecordingMethod(),
    )
    sampleTime = sampleTime.plus(java.time.Duration.ofMinutes(minutesBetweenSamples))
}
healthConnectClient.insertRecords(
    stepsRecords
)

Weitere Informationen finden Sie in der Dokumentation zu ZoneId.

Passives Tracking

Dazu gehören Apps, die passives Fitness- oder Gesundheitstracking durchführen, z. B. Schritte oder die Herzfrequenz kontinuierlich im Hintergrund aufzeichnen.

Ihre App muss regelmäßig Daten in Health Connect schreiben. Dies kann auf folgende Weise erfolgen:

• Schreiben Sie bei jeder Synchronisierung nur neue Daten und aktualisierte Daten, die seit der letzten Synchronisierung geändert wurden.
• Chunk-Anfragen mit maximal 1.000 Datensätzen pro Schreibanfrage.
• Verwenden Sie WorkManager, um regelmäßige Hintergrundaufgaben mit einem Zeitraum von mindestens 15 Minuten zu planen.
• Aufgaben dürfen nur ausgeführt werden, wenn das Gerät inaktiv ist und der Akkustand nicht niedrig ist.

val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Aktives Tracking

Dazu gehören Apps, die ereignisbasiertes Tracking durchführen, z. B. für Training und Schlaf, oder manuelle Nutzereingaben wie Ernährung. Diese Datensätze werden erstellt, wenn sich die App im Vordergrund befindet oder in seltenen Fällen, wenn sie mehrmals am Tag verwendet wird.

Achte darauf, dass deine App Health Connect nicht während der gesamten Dauer des Ereignisses im Hintergrund ausführt.

Daten müssen auf eine von zwei Arten in Health Connect geschrieben werden:

• Daten nach Abschluss des Ereignisses mit Health Connect synchronisieren Synchronisieren Sie beispielsweise Daten, wenn der Nutzer ein aufgezeichnetes Training beendet.
• Planen Sie mit WorkManager eine einmalige Aufgabe, um Daten später zu synchronisieren.

Best Practices für Granularität und Häufigkeit von Schreibvorgängen

Verwenden Sie beim Schreiben von Daten in Health Connect eine angemessene Auflösung. Wenn Sie die richtige Auflösung verwenden, können Sie die Speicherbelastung reduzieren und gleichzeitig konsistente und genaue Daten beibehalten. Die Datenauflösung umfasst zwei Aspekte:

1. Häufigkeit der Schreibvorgänge: Wie oft Ihre Anwendung neue Daten in Health Connect überträgt. Beispiel: Alle 15 Minuten neue Daten schreiben.
2. Granularität der geschriebenen Daten: Wie oft wurden die Daten, die übertragen wurden, erhoben? Schreibe beispielsweise alle 5 Sekunden Herzfrequenz-Messwerte. Nicht für jeden Datentyp ist dieselbe Stichprobenrate erforderlich. Es bringt wenig, die Schrittzahldaten jede Sekunde zu aktualisieren. Eine weniger häufige Aktualisierung, z. B. alle 60 Sekunden, ist ausreichend. Höhere Stichprobenraten können Nutzern jedoch einen detaillierteren und genaueren Einblick in ihre Gesundheits- und Fitnessdaten geben. Die Häufigkeit der Abtastrate sollte ein ausgewogenes Verhältnis zwischen Detail und Leistung bieten.

Den ganzen Tag über überwachte Daten schreiben

Bei Daten, die fortlaufend erfasst werden, z. B. Schritte, sollte Ihre Anwendung mindestens alle 15 Minuten Daten in Health Connect schreiben.

Sitzungen schreiben

Daten sollten am Ende des Trainings oder der Schlafsitzung in Health Connect geschrieben werden.

Ihre Anwendung sollte mindestens die Richtlinien in der Spalte Erwartet in der folgenden Tabelle einhalten. Folgen Sie nach Möglichkeit den Best Practices.

Trainings- und Schlafeinheiten

Das folgende Beispiel zeigt, wie Daten während eines Trainings geschrieben werden:

Das folgende Beispiel zeigt, wie Daten während oder nach einer Schlafaufzeichnung geschrieben werden:

Mehrdisziplin-Wettkämpfe

Bei diesem Ansatz werden vorhandene Datentypen und ‑strukturen verwendet und die Kompatibilität mit aktuellen Health Connect-Implementierungen und Datenlesern wird überprüft. Das ist ein gängiger Ansatz bei Fitnessplattformen.

Im folgenden Beispiel wird gezeigt, wie Daten für einen Triathlon geschrieben werden:

val swimStartTime = Instant.parse("2024-08-22T08:00:00Z")
val swimEndTime = Instant.parse("2024-08-22T08:30:00Z")
val bikeStartTime = Instant.parse("2024-08-22T08:40:00Z")
val bikeEndTime = Instant.parse("2024-08-22T09:40:00Z")
val runStartTime = Instant.parse("2024-08-22T09:50:00Z")
val runEndTime = Instant.parse("2024-08-22T10:20:00Z")

val swimSession = ExerciseSessionRecord(
    startTime = swimStartTime,
    endTime = swimEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_SWIMMING_OPEN_WATER,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val bikeSession = ExerciseSessionRecord(
    startTime = bikeStartTime,
    endTime = bikeEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val runSession = ExerciseSessionRecord(
    startTime = runStartTime,
    endTime = runEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

healthConnectClient.insertRecords(listOf(swimSession, bikeSession, runSession))