Ab 2026 werden wir die Google Fit-APIs nicht mehr unterstützen. Weitere Informationen zur Google Fit-Migration findest du im Migrationsleitfaden.

Diese Seite wurde von der Cloud Translation API übersetzt.

Daten synchronisieren

Dieser Leitfaden ist mit Health Connect-Version 1.1.0-alpha12 kompatibel.

Die meisten Apps, die in Health Connect eingebunden sind, haben einen eigenen Datenspeicher, der als „Source of Truth“ dient. Health Connect bietet Möglichkeiten, Ihre App zu synchronisieren.

Je nach Architektur Ihrer App kann der Synchronisierungsvorgang einige oder alle der folgenden Aktionen umfassen:

Neue oder aktualisierte Daten aus dem Datenspeicher Ihrer App an Health Connect senden.
Datenänderungen aus Health Connect in den Datenspeicher Ihrer App abrufen
Daten aus Health Connect löschen, wenn sie im Datenspeicher Ihrer App gelöscht werden

Achten Sie in jedem Fall darauf, dass der Synchronisierungsprozess sowohl Health Connect als auch den Datenspeicher Ihrer App auf dem neuesten Stand hält.

Daten an Health Connect senden

Im ersten Teil des Synchronisierungsvorgangs werden Daten aus dem Datenspeicher Ihrer App in den Health Connect-Datenspeicher übertragen.

Daten vorbereiten

In der Regel enthalten Datensätze im Datastore Ihrer App die folgenden Details:

Ein eindeutiger Schlüssel, z. B. ein UUID.
Eine Version oder ein Zeitstempel.

Wenn Sie Daten mit Health Connect synchronisieren, identifizieren und übertragen Sie nur die Daten, die seit der letzten Synchronisierung eingefügt, aktualisiert oder gelöscht wurden.

Daten in Health Connect schreiben

So übertragen Sie Daten an Health Connect:

Eine Liste mit neuen, aktualisierten oder gelöschten Einträgen aus dem Datenspeicher Ihrer App abrufen.
Erstellen Sie für jeden Eintrag ein Record-Objekt, das für diesen Datentyp geeignet ist. Erstellen Sie beispielsweise ein WeightRecord-Objekt für Daten zum Gewicht.

Geben Sie für jeden Record ein Metadata-Objekt an. Dazu gehört auch clientRecordId, eine ID aus dem Datenspeicher Ihrer App, mit der Sie den Datensatz eindeutig identifizieren können. Sie können dafür Ihren vorhandenen eindeutigen Schlüssel verwenden. Wenn Ihre Daten versioniert sind, geben Sie auch eine clientRecordVersion an, die mit der in Ihren Daten verwendeten Versionierung übereinstimmt. Wenn sie nicht versioniert ist, können Sie stattdessen den Long-Wert des aktuellen Zeitstempels verwenden.

val recordVersion = 0L
// Specify as needed
// The clientRecordId is an ID that you choose for your record. This
// is often the same ID you use in your app's datastore.
val clientRecordId = "<your-record-id>"

val record = WeightRecord(
    metadata = Metadata.activelyRecorded(
        clientRecordId = clientRecordId,
        clientRecordVersion = recordVersion,
        device = Device(type = Device.TYPE_SCALE)
    ),
    weight = Mass.kilograms(62.0),
    time = Instant.now(),
    zoneOffset = ZoneOffset.UTC,
)
healthConnectClient.insertRecords(listOf()(record))

Upsert-Daten in Health Connect mit insertRecords. Beim Upserting von Daten werden alle vorhandenen Daten in Health Connect überschrieben, sofern die clientRecordId-Werte im Health Connect-Datenspeicher vorhanden sind und der clientRecordVersion-Wert höher als der vorhandene Wert ist. Andernfalls werden die eingefügten Daten als neue Daten geschrieben.
```
healthConnectClient.insertRecords(arrayListOf(record))
```

Informationen zu den praktischen Aspekten der Datenübertragung finden Sie unter Daten schreiben.

Health Connect-IDs speichern

Wenn Ihre App auch Daten aus Health Connect liest, speichern Sie die Health Connect-id für Datensätze, nachdem Sie sie eingefügt oder aktualisiert haben. Sie benötigen diese id, um Löschvorgänge zu verarbeiten, wenn Sie Datenänderungen aus Health Connect abrufen.

Die Funktion insertRecords gibt ein InsertRecordsResponse zurück, das die Liste der id-Werte enthält. Verwenden Sie die Antwort, um die Datensatz-IDs abzurufen und zu speichern.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

Daten aus Health Connect abrufen

Im zweiten Teil des Synchronisierungsvorgangs werden alle Datenänderungen von Health Connect in den Datenspeicher Ihrer App übertragen. Die Datenänderungen können Aktualisierungen und Löschungen umfassen.

Changes-Token abrufen

Damit deine App eine Liste der Änderungen abrufen kann, die aus Health Connect übernommen werden sollen, muss sie Changes-Tokens im Blick behalten. Sie können sie verwenden, wenn Sie Changes anfordern, um sowohl eine Liste der Datenänderungen als auch ein neues Changes-Token zurückzugeben, das beim nächsten Mal verwendet werden soll.

Rufen Sie getChangesToken auf und geben Sie die erforderlichen Datentypen an, um ein Changes-Token zu erhalten.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

Nach Datenänderungen suchen

Nachdem Sie ein Changes-Token erhalten haben, können Sie damit alle Changes abrufen. Wir empfehlen, eine Schleife zu erstellen, um alle Changes (Änderungen) zu durchlaufen und zu prüfen, ob Datenänderungen verfügbar sind. So gehts:

Rufen Sie getChanges mit dem Token auf, um eine Liste der Änderungen abzurufen.
Prüfen Sie für jede Änderung, ob es sich um eine UpsertionChange oder eine DeletionChange handelt, und führen Sie die erforderlichen Vorgänge aus.
- Für UpsertionChange sollten Sie nur Änderungen berücksichtigen, die nicht von der Anrufer-App stammen, damit Sie keine Daten noch einmal importieren.
Weisen Sie das nächste Changes-Token als neues Token zu.
Wiederholen Sie die Schritte 1 bis 3, bis keine Änderungen mehr vorhanden sind.
Speichern Sie das nächste Token und reservieren Sie es für einen zukünftigen Import.

suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

Informationen zu den praktischen Aspekten des Abrufens von Daten finden Sie unter Daten synchronisieren.

Datenänderungen verarbeiten

Die Änderungen im Datenspeicher Ihrer App widerspiegeln. Verwenden Sie für UpsertionChange die id und die lastModifiedTime aus dem metadata, um den Datensatz upsert. Verwenden Sie für DeletionChange die bereitgestellte id, um den Datensatz zu löschen. Dazu müssen Sie den Datensatz id wie unter Health Connect-IDs speichern beschrieben gespeichert haben.

Daten aus Health Connect löschen

Wenn ein Nutzer seine eigenen Daten aus Ihrer App löscht, müssen Sie dafür sorgen, dass die Daten auch aus Health Connect entfernt werden. Verwenden Sie dazu deleteRecords. Dazu sind ein Datensatztyp und eine Liste von id- und clientRecordId-Werten erforderlich. So lassen sich mehrere Daten bequem in einem Batch löschen. Alternativ ist auch deleteRecords verfügbar, das timeRangeFilter akzeptiert.

Best Practices für die Synchronisierung von Daten

Die folgenden Faktoren wirken sich auf den Synchronisierungsvorgang aus.

Ablauf des Tokens

Da ein ungenutztes Changes-Token innerhalb von 30 Tagen abläuft, müssen Sie eine Synchronisierungsstrategie verwenden, die in einem solchen Fall Datenverlust vermeidet. Ihre Strategie könnte die folgenden Ansätze umfassen:

Suchen Sie im Datenspeicher Ihrer App nach dem zuletzt verwendeten Datensatz, der auch eine id aus Health Connect enthält.
Sie können Datensätze von Health Connect anfordern, die mit einem bestimmten Zeitstempel beginnen, und sie dann in den Datenspeicher Ihrer App einfügen oder aktualisieren.
Fordern Sie ein Changes-Token an, um es für die nächste Verwendung zu reservieren.

Empfohlene Strategien für das Änderungsmanagement

Falls Ihre App ungültige oder abgelaufene Changes-Tokens erhält, empfehlen wir die folgenden Verwaltungsstrategien, je nachdem, wie sie in Ihrer Logik angewendet werden:

Alle Daten lesen und deduplizieren: Das ist die beste Strategie.
- Speichern des Zeitstempels des letzten Lesens von Daten aus Health Connect.
- Wenn das Token abläuft, lesen Sie alle Daten ab dem letzten Zeitstempel oder für die letzten 30 Tage noch einmal. Anschließend werden die Daten anhand von Kennungen mit den zuvor gelesenen Daten dedupliziert.
- Idealerweise sollten Sie Client-IDs implementieren, da sie für Datenaktualisierungen erforderlich sind.
Nur Daten seit dem letzten Zeitstempel für den Lesevorgang lesen: Dies führt zu einigen Datenabweichungen um den Zeitpunkt des Ablaufs des Changes-Tokens. Der Zeitraum ist jedoch kürzer und kann einige Stunden bis einige Tage dauern.
- Speichern des Zeitstempels des letzten Lesens von Daten aus Health Connect.
- Lesen Sie nach Ablauf des Tokens alle Daten ab diesem Zeitstempel.
Daten der letzten 30 Tage löschen und dann lesen: Das entspricht eher dem, was bei der ersten Integration passiert.
- Alle Daten löschen, die von der App in den letzten 30 Tagen aus Health Connect gelesen wurden.
- Lies alle diese Daten noch einmal.
Lesen von Daten der letzten 30 Tage ohne Deduplizierung: Das ist die am wenigsten ideale Strategie, da Nutzern doppelte Daten angezeigt werden.
- Alle Daten löschen, die von der App in den letzten 30 Tagen aus Health Connect gelesen wurden.
- Doppelte Einträge zulassen.

Tokens für Änderungen des Datentyps

Wenn Ihre App mehrere Datentypen unabhängig voneinander verwendet, verwenden Sie für jeden Datentyp separate Changes-Tokens. Verwenden Sie eine Liste mit mehreren Datentypen mit der Changes Sync API nur, wenn diese Datentypen entweder zusammen oder gar nicht verwendet werden.

Lesevorgänge im Vordergrund

Apps können nur dann Daten aus Health Connect lesen, wenn sie im Vordergrund ausgeführt werden. Beim Synchronisieren von Daten aus Health Connect kann der Zugriff auf Health Connect jederzeit unterbrochen werden. Ihre App muss beispielsweise Unterbrechungen während einer Synchronisierung verarbeiten können, wenn eine große Menge an Daten aus Health Connect gelesen wird, und die Synchronisierung beim nächsten Öffnen der App fortsetzen.

Lesevorgänge im Hintergrund

Sie können anfordern, dass Ihre Anwendung im Hintergrund ausgeführt wird und Daten aus Health Connect liest. Wenn Sie die Berechtigung Background Read anfordern, kann der Nutzer Ihrer App Zugriff zum Lesen von Daten im Hintergrund gewähren.

Importzeitangaben

Da Ihre App nicht über neue Daten benachrichtigt werden kann, müssen Sie an zwei Stellen nach neuen Daten suchen:

Jedes Mal, wenn Ihre App im Vordergrund aktiv wird. Verwenden Sie in diesem Fall Lifecycle-Events.
Regelmäßig, während Ihre App im Vordergrund ausgeführt wird. Nutzer benachrichtigen, wenn neue Daten verfügbar sind, damit sie ihren Bildschirm aktualisieren können, um die Änderungen zu sehen.