Google Fit-APIs werden bis Ende 2026 unterstützt. Informationen zu den empfohlenen Migrationspfaden finden Sie im Migrationsleitfaden.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Daten synchronisieren

Diese Anleitung 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 Quelle der Wahrheit dient. Health Connect bietet Möglichkeiten, deine App zu synchronisieren.

Je nach Architektur deiner App kann der Synchronisierungsprozess einige oder alle der folgenden Aktionen umfassen:

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

In jedem Fall muss der Synchronisierungsprozess sowohl Health Connect als auch den Datenspeicher deiner App auf dem neuesten Stand halten.

Daten an Health Connect senden

Im ersten Teil des Synchronisierungsprozesses werden Daten aus dem Datenspeicher deiner App an den Health Connect-Datenspeicher gesendet.

Daten vorbereiten

In der Regel enthalten Datensätze im Datenspeicher deiner App die folgenden Details:

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

Wenn du Daten mit Health Connect synchronisierst, identifiziere und sende nur die Daten, die seit der letzten Synchronisierung eingefügt, aktualisiert oder gelöscht wurden.

Daten in Health Connect schreiben

So sendest du Daten an Health Connect:

Rufe eine Liste der neuen, aktualisierten oder gelöschten Einträge aus dem Datenspeicher deiner App ab.
Erstelle für jeden Eintrag ein Record-Objekt, das für diesen Datentyp geeignet ist. Erstelle beispielsweise ein WeightRecord-Objekt für Daten zum Gewicht.

Gib für jeden Record ein Metadata-Objekt an. Dazu gehört clientRecordId, eine ID aus dem Datenspeicher deiner App, mit der du den Datensatz eindeutig identifizieren kannst. Du kannst dafür deinen vorhandenen eindeutigen Schlüssel verwenden. Wenn deine Daten versioniert sind, gib auch eine clientRecordVersion an, die mit der in deinen Daten verwendeten Versionierung übereinstimmt. Wenn sie nicht versioniert sind, kannst du alternativ 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(
        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))HealthConnectManager.kt

Führe mit insertRecords ein Upsert für Daten in Health Connect durch. Das bedeutet, dass alle vorhandenen Daten in Health Connect überschrieben werden, solange die clientRecordId-Werte im Health Connect-Datenspeicher vorhanden sind und die clientRecordVersion höher als der vorhandene Wert ist. Andernfalls werden die Upsert-Daten als neue Daten geschrieben.
```
healthConnectClient.insertRecords(arrayListOf(record))HealthConnectManager.kt
```

Informationen zu den praktischen Überlegungen beim Senden von Daten findest du unter Best Practices für das Schreiben von Daten.

Health Connect-IDs speichern

Wenn deine App auch Daten aus Health Connect liest, speichere die Health Connect-id für Datensätze, nachdem du sie mit Upsert eingefügt hast. Du benötigst diese id, um Löschvorgänge zu verarbeiten, wenn du Datenänderungen aus Health Connect abrufst.

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

val response = healthConnectClient.insertRecords(listOf(record))
for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}HealthConnectManager.kt

Daten aus Health Connect abrufen

Im zweiten Teil des Synchronisierungsprozesses werden alle Datenänderungen aus Health Connect in den Datenspeicher deiner App übernommen. Zu den Datenänderungen können Aktualisierungen und Löschvorgänge gehören.

Änderungstoken abrufen

Um eine Liste der Änderungen abzurufen, die aus Health Connect übernommen werden sollen, muss deine App Änderungstoken verfolgen. Du kannst sie verwenden, wenn du Änderungen anforderst, um sowohl eine Liste der Datenänderungen als auch ein neues Änderungstoken für die nächste Verwendung zurückzugeben.

Rufe getChangesToken auf und gib die erforderlichen Datentypen an, um ein Änderungstoken zu erhalten.

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

Auf Datenänderungen prüfen

Nachdem du ein Änderungstoken erhalten hast, kannst du damit alle Änderungen abrufen. Wir empfehlen, eine Schleife zu erstellen, um alle Änderungen zu durchlaufen und zu prüfen, ob Datenänderungen verfügbar sind. Hier sind die Schritte:

Rufe getChanges mit dem Token auf, um eine Liste der Änderungen zu erhalten.
Prüfe für jede Änderung, ob es sich um ein UpsertionChange oder eine DeletionChange handelt, und führe die erforderlichen Vorgänge aus.
- Nimm bei UpsertionChange nur Änderungen vor, die nicht von der aufrufenden App stammen, damit du keine Daten neu importierst.
Weise das nächste Änderungstoken als neues Token zu.
Wiederhole die Schritte 1 bis 3, bis keine Änderungen mehr vorhanden sind.
Speichere das nächste Token und reserviere es für einen zukünftigen Import.

suspend fun processChanges(context: Context, 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
}HealthConnectManager.kt

Informationen zu den praktischen Überlegungen beim Abrufen von Daten findest du unter Best Practices für das Synchronisieren von Daten.

Datenänderungen verarbeiten

Übertrage die Änderungen in den Datenspeicher deiner App. Verwende für UpsertionChange die id und die lastModifiedTime aus den metadata, um den Datensatz mit Upsert einzufügen. Verwende für DeletionChange die angegebene id, um den Datensatz zu löschen. Dazu musst du den Datensatz id wie unter Health Connect-IDs speichern beschrieben gespeichert haben.

Daten aus Health Connect löschen

Wenn ein Nutzer seine Daten aus deiner App löscht, müssen sie auch aus Health Connect entfernt werden. Verwende deleteRecords dazu. Diese Funktion akzeptiert einen Datensatztyp und eine Liste von id- und clientRecordId-Werten, sodass du mehrere Daten gleichzeitig löschen kannst. An alternative deleteRecords das einen timeRangeFilter akzeptiert ist auch verfügbar.

Synchronisierung mit niedriger Latenz von Wearables

Verwende CompanionDeviceService, um Daten mit niedriger Latenz von einem Fitness-Wearable mit Health Connect zu synchronisieren. Dieser Ansatz funktioniert für Geräte, die BLE GATT-Benachrichtigungen oder -Hinweise unterstützen und auf Android 8.0 (API-Ebene 26) oder höher ausgerichtet sind. Mit CompanionDeviceService kann deine App Daten von Wearables empfangen und in Health Connect schreiben, auch wenn die App nicht bereits ausgeführt wird. Weitere Informationen zu BLE-Best Practices findest du unter Bluetooth Low Energy – Übersicht.

Gerät verknüpfen

Zuerst muss deine App den Nutzer durch einen einmaligen Prozess führen, um das Wearable mit deiner App mit CompanionDeviceManager zu verknüpfen. Dadurch erhält deine App die erforderlichen Berechtigungen für die Interaktion mit dem Gerät. Weitere Informationen findest du unter Gerätekopplung mit Begleitgeräten.

Dienst im Manifest deklarieren

Deklariere als Nächstes CompanionDeviceService in der Manifestdatei deiner App. Füge Folgendes zu AndroidManifest.xml hinzu:

<manifest ...>
   <application ...>
       <service
           android:name=".MyWearableService"
           android:exported="true"
           android:permission="android.permission.BIND_COMPANION_DEVICE_SERVICE">
           <intent-filter>
               <action android:name="android.companion.CompanionDeviceService" />
           </intent-filter>
       </service>
   </application>
</manifest>

CompanionDeviceService erstellen

Erstelle schließlich eine Klasse, die CompanionDeviceService erweitert. Dieser Dienst verarbeitet die Verbindung zum Wearable und empfängt Daten über BLE GATT-Callbacks. Wenn neue Daten empfangen werden, werden sie sofort in Health Connect geschrieben.

private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
private var healthConnectClient: HealthConnectClient? = null
private var bluetoothGatt: BluetoothGatt? = null

override fun onDeviceAppeared(address: String) {
    super.onDeviceAppeared(address)
    healthConnectClient = HealthConnectClient.getOrCreate(this)

    serviceScope.launch {
        val granted = healthConnectClient?.permissionController?.getGrantedPermissions()

        // 1. Check permissions ONCE when the device connects
        if (granted?.contains(HealthPermission.getWritePermission(HeartRateRecord::class)) ?: false) {
            // This is where you'd actually start the Bluetooth connection
            // bluetoothGatt = gattCallback.connect(...)
        }

        // 2. Do your initial database read
        readExerciseSessionAndRoute()
    }
}

private val gattCallback = object : BluetoothGattCallback() {
    override fun onCharacteristicChanged(
        gatt: BluetoothGatt,
        characteristic: BluetoothGattCharacteristic,
        value: ByteArray
    ) {
        super.onCharacteristicChanged(gatt, characteristic, value)

        // 3. ONLY process the incoming data here
        val rawData = value

        serviceScope.launch {
            // parseWearableData(rawData)
            // insertExerciseRoute() or writeToHealthConnect()
        }
    }
}MyWearableService.kt

Best Practices für das Synchronisieren von Daten

Die folgenden Faktoren wirken sich auf den Synchronisierungsprozess aus.

Ablauf des Tokens

Da ein nicht verwendetes Änderungstoken innerhalb von 30 Tagen abläuft, musst du eine Synchronisierungsstrategie verwenden, mit der in diesem Fall keine Informationen verloren gehen. Deine Strategie könnte die folgenden Ansätze umfassen:

Suche im Datenspeicher deiner App nach dem zuletzt verwendeten Datensatz, der auch eine id von Health Connect hat.
Fordere Datensätze von Health Connect an, die mit einem bestimmten Zeitstempel beginnen, und füge sie dann in den Datenspeicher deiner App ein oder aktualisiere sie dort.
Fordere ein Änderungstoken an, um es für die nächste Verwendung zu reservieren.

Empfohlene Strategien für die Verwaltung von Änderungen

Wenn deine App ungültige oder abgelaufene Änderungstoken erhält, empfehlen wir die folgenden Verwaltungsstrategien, je nachdem, wie sie in deiner Logik angewendet werden:

Alle Daten lesen und deduplizieren. Dies ist die beste Strategie.
- Speichere den Zeitstempel des letzten Lesevorgangs von Daten aus Health Connect.
- Wenn das Token abläuft, lies alle Daten ab dem letzten Zeitstempel oder der letzten 30 Tage noch einmal. Dedupliziere sie dann anhand von Kennungen mit den zuvor gelesenen Daten.
- Implementiere idealerweise Client-IDs, da sie für Datenaktualisierungen erforderlich sind.
Nur Daten seit dem letzten Zeitstempel lesen. Dies führt zu einigen Datenabweichungen um den Zeitpunkt des Ablaufs des Änderungstokens, aber der Zeitraum ist kürzer und kann einige Stunden bis einige Tage dauern.
- Speichere den Zeitstempel des letzten Lesevorgangs von Daten aus Health Connect.
- Wenn das Token abläuft, lies alle Daten ab diesem Zeitstempel.
Daten der letzten 30 Tage löschen und dann lesen. Dies entspricht eher dem, was bei der ersten Einbindung passiert.
- Lösche alle Daten, die von der App in den letzten 30 Tagen aus Health Connect gelesen wurden.
- Lies alle diese Daten noch einmal.
Daten der letzten 30 Tage ohne Deduplizierung lesen. Dies ist die am wenigsten ideale Strategie und führt dazu, dass Nutzern doppelte Daten angezeigt werden.
- Lösche alle Daten, die von der App in den letzten 30 Tagen aus Health Connect gelesen wurden.
- Doppelte Einträge zulassen.

Änderungstoken für Datentypen

Wenn deine App mehrere Datentypen unabhängig voneinander verwendet, verwende separate Änderungstoken für jeden Datentyp. Verwende nur eine Liste mit mehreren Datentypen mit der Changes Sync API, wenn diese Datentypen entweder zusammen oder gar nicht verwendet werden.

Lesevorgänge im Vordergrund

Apps können nur 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. Deine App muss beispielsweise Unterbrechungen während der Synchronisierung verarbeiten, wenn eine große Menge an Daten aus Health Connect gelesen wird, und den Vorgang fortsetzen, wenn die App das nächste Mal geöffnet wird.

Lesevorgänge im Hintergrund

Du kannst anfordern, dass deine Anwendung im Hintergrund ausgeführt wird und Daten aus Health Connect liest. Wenn du die Background Read Berechtigung anforderst, kann der Nutzer deiner App Zugriff auf das Lesen von Daten im Hintergrund gewähren.

Importzeiten

Da deine App nicht über neue Daten benachrichtigt werden kann, prüfe an zwei Stellen auf neue Daten:

Jedes Mal, wenn deine App im Vordergrund aktiv wird. Verwende in diesem Fall Lebenszyklusereignisse.
In regelmäßigen Abständen, während deine App im Vordergrund bleibt. Benachrichtige Nutzer, wenn neue Daten verfügbar sind, damit sie ihren Bildschirm aktualisieren können, um die Änderungen zu sehen.

Zurück

Daten löschen

Weiter

Anforderungen an Metadaten