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.

Umgang mit Nullwerten

Einige Datentypen wie Schritte, Entfernung oder Kalorien haben möglicherweise den Wert 0. Schreibe nur 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 ein gängiger Messwert auf Gesundheits-, Fitness- und Wellnessplattformen.

Das folgende Beispiel zeigt, wie Schrittzählerdaten festgelegt werden:

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))
HealthConnectManager.kt

Datensätze mit Maßeinheiten

Health Connect kann Werte zusammen mit ihren Maßeinheiten speichern, um die Genauigkeit zu gewährleisten. Ein Beispiel ist der Datentyp Ernährung, 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.

In diesem Datentyp werden alle Nährstoffe in Einheiten von Masse und energy in Einheiten von Energie angegeben.

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.activelyRecorded(
        device = Device(type = Device.TYPE_PHONE)
    )
)
HealthConnectManager.kt

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 den Messungen erkannt wurden.

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

Im folgenden Beispiel wird gezeigt, wie Daten für die Herzfrequenzreihe festgelegt werden:

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.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))
HealthConnectManager.kt

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.

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::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

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:

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))
HealthConnectManager.kt

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 Methode verwendet wird, hängt vom Bezeichner ab, mit dem Datensätze gesucht werden.

Metadaten

Sehen Sie sich zuerst die Klasse Metadata an, da sie für das Aktualisieren von Daten erforderlich ist. Beim Erstellen hat jedes Record in Health Connect ein Feld metadata. Die folgenden Properties 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
    }
}
HealthConnectManager.kt

Upsert über Client-Datensatz-ID

Wenn Sie die optionalen Werte „Client Record ID“ (Client-Datensatz-ID) und „Client Record Version“ (Client-Datensatz-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.

Im folgenden Beispiel wird gezeigt, wie ein Upsert für Daten ausgeführt wird, die aus dem App-Datenspeicher abgerufen wurden:

 fun pullStepsFromDatastore(startTime: Instant, endTime: Instant) : 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.activelyRecorded(
            clientRecordId = "Your client record ID",
            clientRecordVersion = 0L,
            device = Device(type = Device.TYPE_WATCH)
        ),
        startTime = startTime,
        startZoneOffset = startTime.atZone(ZoneId.of("PST")).offset,
        endTime = endTime,
        endZoneOffset = endTime.atZone(ZoneId.of("PST")).offset,
        count = 120
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

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

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

upsertSteps(healthConnectClient, pullStepsFromDatastore(
    startTime = startTime,
    endTime = endTime
))
HealthConnectManager.kt

Wertprüfung in der Client-Datensatzversion

Wenn Ihr Prozess zum Einfügen und Aktualisieren von Daten die Client Record Version umfasst, führt Health Connect Vergleichsprüfungen für die clientRecordVersion-Werte durch. Wenn die Version der eingefügten Daten höher ist als die Version der 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 einen Long-Wert basierend auf Ihrer Versionsverwaltungslogik bereitstellen.

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.activelyRecorded(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)
HealthConnectManager.kt

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.

Allgemeine Anleitung

Ihre App sollte alle unterstützten selbst erhobenen Daten schreiben. Optional können Sie festlegen, dass Ihre App Daten aus Drittanbieterquellen schreibt. Wenn Ihre App jedoch Daten aus Health Connect gelesen hat, sollten diese Daten nicht wieder in Health Connect geschrieben werden.

Wenn Sie Daten schreiben, die aus einer anderen Quelle importiert oder abgeleitet wurden, müssen Sie die Herkunft und die Metadaten des Quellgeräts korrekt angeben. Dazu müssen Sie für jeden schriftlichen Eintrag die folgenden Metadaten angeben:

• recordingMethod: Bei automatisch oder manuell aufgezeichneten Daten muss die Aufzeichnungsmethode aktualisiert werden, um den Typ der aufgezeichneten Aktivität widerzuspiegeln:
  • RECORDING_METHOD_AUTOMATICALLY_RECORDED: Wenn die Daten automatisch aufgezeichnet wurden, z. B. wenn ein Fitness-Tracker automatisch erkannt hat, dass der Nutzer joggen war.
  • RECORDING_METHOD_ACTIVELY_RECORDED: Wenn der Nutzer eine neue Aktivität gestartet hat, z. B. Radfahren auf seinem Wearable.
  • RECORDING_METHOD_MANUAL_ENTRY: Gibt an, ob der Nutzer die Daten manuell eingegeben hat.
• device.type: Sie müssen einen Gerätetyp aus einem der unterstützten Device-Typen angeben.
• device.manufacturer: Der Hersteller des Geräts, z. B. „Fitbit“.
• device.model: Das Modell des Geräts, z. B. „Charge 3“.
• device.udi: (Optional) Der Teil der eindeutigen Gerätekennung (Unique Device Identifier, UDI) des Medizinprodukts, der die Gerätekennung (Device Identifier, DI) enthält. Weitere Informationen zu den erforderlichen Berechtigungen und Datenschutzrichtlinien finden Sie im Leitfaden zu Metadaten.

Das korrekte Festlegen von Metadaten ist entscheidend für die Datentransparenz und hilft Nutzern, nachzuvollziehen, woher ihre Gesundheitsinformationen stammen. Ausführliche Informationen finden Sie im Health Connect-Metadatenguide.

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 auch, Logik zu implementieren, die Schreibausnahmen wie Daten außerhalb des zulässigen Bereichs oder einen internen Systemfehler verarbeitet. 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 beachten 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 Offset 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(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(Duration.ofMinutes(minutesBetweenSamples)),
        startZoneOffset = zoneOffset,
        endTime = sampleTime,
        endZoneOffset = zoneOffset,
        count = Random.nextLong(1, 100),
        metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    )
    sampleTime = sampleTime.plus(Duration.ofMinutes(minutesBetweenSamples))
}
healthConnectClient.insertRecords(
    stepsRecords
)
HealthConnectManager.kt

Weitere Informationen finden Sie in der Dokumentation zu ZoneId.

Schreibhäufigkeit und ‑detaillierungsgrad

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

• Häufigkeit der Schreibvorgänge: Wie oft Ihre Anwendung neue Daten in Health Connect schreibt.
  • Schreiben Sie Daten so oft wie möglich, wenn neue Daten verfügbar sind, und achten Sie dabei auf die Geräteleistung.
  • Um die Akkulaufzeit und andere Leistungsaspekte nicht negativ zu beeinträchtigen, sollte das maximale Intervall zwischen Schreibvorgängen 15 Minuten betragen.
• Granularität der geschriebenen Daten: Wie oft die Daten erhoben wurden.
  • Schreibe beispielsweise alle 5 Sekunden Herzfrequenzmesswerte.
  • 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 einen detaillierteren und genaueren Einblick in ihre Gesundheits- und Fitnessdaten geben. Die Häufigkeit der Stichprobenrate sollte ein Gleichgewicht zwischen Detail und Leistung herstellen.

Zusätzliche Richtlinien

Beachten Sie beim Schreiben von Daten die folgenden Richtlinien:

• Bei jeder Synchronisierung werden nur neue Daten und aktualisierte Daten geschrieben, die seit der letzten Synchronisierung geändert wurden.
• Chunk-Anfragen mit maximal 1.000 Datensätzen pro Schreibanfrage.
• Beschränken Sie die Ausführung von Aufgaben auf Zeiten, in denen das Gerät im Leerlauf ist und der Akkustand nicht niedrig ist.
• Verwenden Sie für Hintergrundaufgaben WorkManager, um regelmäßige Aufgaben mit einem maximalen Zeitraum von 15 Minuten zu planen.

Im folgenden Code wird WorkManager verwendet, um periodische Hintergrundaufgaben mit einem maximalen Zeitraum von 15 Minuten und einem flexiblen Intervall von 5 Minuten zu planen. Diese Konfiguration wird mit der Klasse PeriodicWorkRequest.Builder festgelegt.

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.

Prüfen Sie, ob Ihre App Health Connect nicht für die gesamte Dauer des Ereignisses ausführt.

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

• Daten nach Abschluss des Ereignisses mit Health Connect synchronisieren So können Sie beispielsweise Daten synchronisieren, wenn der Nutzer eine aufgezeichnete Trainingseinheit 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 Speicherlast 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. Schreiben Sie Daten so oft wie möglich, wenn neue Daten verfügbar sind, und achten Sie dabei auf die Geräteleistung. Um die Akkulaufzeit und andere Leistungsaspekte nicht negativ zu beeinträchtigen, sollte das maximale Intervall zwischen Schreibvorgängen 15 Minuten betragen.

2. Granularität der geschriebenen Daten: wie oft die gepushten Daten erhoben wurden. Schreibe beispielsweise alle 5 Sekunden Herzfrequenz-Messwerte. Nicht für jeden Datentyp ist dieselbe Samplingrate erforderlich. Es ist kaum von Vorteil, die Daten zur Schrittzahl jede Sekunde zu aktualisieren, anstatt in einem weniger häufigen Rhythmus, z. B. alle 60 Sekunden. Höhere Abtastraten können Nutzern jedoch einen detaillierteren und genaueren Einblick in ihre Gesundheits- und Fitnessdaten geben. Die Frequenzen der Abtastrate sollten ein ausgewogenes Verhältnis zwischen Detail und Leistung bieten.

Datensätze für Seriendaten strukturieren

Bei Datentypen, die eine Reihe von Messwerten verwenden, z. B. HeartRateRecord, ist es wichtig, dass du deine Datensätze richtig strukturierst. Anstatt einen einzelnen, tageslangen Datensatz zu erstellen, der ständig aktualisiert wird, sollten Sie mehrere kleinere Datensätze erstellen, die jeweils ein bestimmtes Zeitintervall darstellen.

Für Herzfrequenzdaten sollten Sie beispielsweise für jede Minute ein neues HeartRateRecord erstellen. Jeder Datensatz hätte eine Start- und Endzeit für diese Minute und würde alle in dieser Minute erfassten Herzfrequenzmessungen enthalten.

Bei regelmäßigen Synchronisierungen mit Health Connect (z. B. alle 15 Minuten) sollte deine App alle Ein-Minuten-Datensätze schreiben, die seit der letzten Synchronisierung erstellt wurden. So bleiben Datensätze übersichtlich und die Leistung beim Abfragen und Verarbeiten von Daten wird verbessert.

Im folgenden Beispiel wird gezeigt, wie Sie ein HeartRateRecord für eine einzelne Minute mit mehreren Stichproben erstellen:

val startTime = Instant.now().truncatedTo(ChronoUnit.MINUTES)
val endTime = startTime.plus(Duration.ofMinutes(1))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // Create a new record every minute, containing a list of samples.
    samples = listOf(
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(15),
            beatsPerMinute = 80,
        ),
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(30),
            beatsPerMinute = 82,
        ),
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(45),
            beatsPerMinute = 85,
        )
    ),
    metadata = Metadata.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))
HealthConnectManager.kt

Den ganzen Tag über überwachte Daten schreiben

Bei Daten, die fortlaufend erfasst werden, z. B. Schritte, sollte Ihre Anwendung so oft wie möglich in Health Connect schreiben, wenn neue Daten verfügbar sind. Um die Akkulaufzeit und andere Leistungsaspekte nicht negativ zu beeinträchtigen, sollte das maximale Intervall zwischen Schreibvorgängen 15 Minuten betragen.

Daten sollten am Ende des Trainings oder der Schlafsitzung in Health Connect geschrieben werden. Bei der aktiven Aufzeichnung, z. B. von Training und Schlaf, oder bei manuellen Nutzereingaben wie Ernährung werden diese Datensätze erstellt, wenn die App im Vordergrund ist oder in seltenen Fällen, wenn sie mehrmals am Tag verwendet wird.

Prüfen Sie, ob Ihre App Health Connect nicht für die gesamte Dauer des Ereignisses ausführt.

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

• Daten nach Abschluss des Ereignisses mit Health Connect synchronisieren So können Sie beispielsweise Daten synchronisieren, wenn der Nutzer eine aufgezeichnete Trainingseinheit beendet.
• Planen Sie mit WorkManager eine einmalige Aufgabe, um Daten später zu synchronisieren.

Trainingseinheiten und Schlafeinheiten

Ihre Anwendung sollte mindestens den Richtlinien in der Spalte Erwartet in Tabelle 2 entsprechen. Folgen Sie nach Möglichkeit den Empfehlungen in der Spalte Optimal.

In der folgenden Tabelle sehen Sie, wie Daten während eines Trainings geschrieben werden:

In Tabelle 3 sehen Sie, wie Sie Daten während oder nach einer Schlafeinheit schreiben:

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.

Außerdem sind einzelne Trainingseinheiten wie Schwimmen, Radfahren und Laufen in Health Connect nicht von Natur aus verknüpft. Datenleser müssen die Beziehung zwischen diesen Trainingseinheiten anhand ihrer zeitlichen Nähe ableiten. Übergänge zwischen Segmenten, z. B. vom Schwimmen zum Radfahren, werden nicht explizit dargestellt.

Das folgende Beispiel zeigt, 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.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ),
    startZoneOffset = null,
    endZoneOffset = null,
)

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

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

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

Ausnahmen behandeln

Health Connect löst Standardausnahmen für CRUD-Vorgänge aus, wenn ein Problem auftritt. Ihre App sollte jede dieser Ausnahmen abfangen und angemessen behandeln.

Für jede Methode in HealthConnectClient werden die Ausnahmen aufgeführt, die ausgelöst werden können. Im Allgemeinen sollte Ihre App die folgenden Ausnahmen abfangen: