Google Fit API'leri 2026'nın sonuna kadar desteklenecek. Önerilen taşıma yolları hakkında bilgi edinmek için Taşıma kılavuzu'na bakın.

Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Verileri senkronize et

Bu kılavuz, Health Connect 1.1.0-alpha12 veya sonraki sürümlerle uyumludur.

Health Connect ile entegre olan çoğu uygulamanın, doğru bilgi kaynağı olarak hizmet veren kendi veri deposu vardır. Health Connect, uygulamanızı senkronize tutmanın yollarını sunar.

Uygulamanızın mimarisine bağlı olarak senkronizasyon işlemi, aşağıdaki işlemlerin bazılarını veya tümünü içerebilir:

Uygulamanızın veri deposundaki yeni veya güncellenmiş verileri Health Connect'e aktarın.
Health Connect'teki veri değişikliklerini uygulamanızın veri deposuna çekin.
Uygulamanızın veri deposundan silinen verileri Health Connect'ten silme

Her durumda, senkronizasyon işleminin hem Health Connect'i hem de uygulamanızın veri deposunu uyumlu tuttuğundan emin olun.

Health Connect'e veri aktarma

Senkronizasyon sürecinin ilk bölümü, uygulamanızın veri deposundaki verileri Health Connect veri deposuna aktarmaktır.

Verilerinizi hazırlama

Uygulamanızın veri deposundaki kayıtlar genellikle aşağıdaki bilgileri içerir:

UUID gibi benzersiz bir anahtar.
Sürüm veya zaman damgası.

Verileri Health Connect ile senkronize ederken yalnızca son senkronizasyondan sonra eklenen, güncellenen veya silinen verileri tanımlayıp besleyin.

Health Connect'e veri yazma

Health Connect'e veri aktarmak için aşağıdaki adımları uygulayın:

Uygulamanızın veri deposundan yeni, güncellenmiş veya silinmiş girişlerin listesini alma
Her giriş için o veri türüne uygun bir Record nesnesi oluşturun. Örneğin, ağırlıkla ilgili veriler için bir WeightRecord nesnesi oluşturun.

Her Record için bir Metadata nesnesi belirtin. Buna, kaydı benzersiz şekilde tanımlamak için kullanabileceğiniz, uygulamanızın veri deposundaki bir kimlik olan clientRecordId dahildir. Bunun için mevcut benzersiz anahtarınızı kullanabilirsiniz. Verileriniz sürümlendirilmişse verilerinizde kullanılan sürümlendirmeyle uyumlu bir clientRecordVersion da sağlayın. Sürüm oluşturulmamışsa alternatif olarak geçerli zaman damgasının Long değerini kullanabilirsiniz.

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))HealthConnectManager.kt

insertRecords kullanarak Health Connect'e veri ekleme veya güncelleme Verileri ekleme ve güncelleme, Health Connect'teki mevcut verilerin üzerine yazılması anlamına gelir. Bunun için clientRecordId değerlerinin Health Connect veri deposunda bulunması ve clientRecordVersion değerinin mevcut değerden yüksek olması gerekir. Aksi takdirde, eklenen veriler yeni veri olarak yazılır.
```
healthConnectClient.insertRecords(arrayListOf(record))HealthConnectManager.kt
```

Veri beslemeyle ilgili pratik konular hakkında bilgi edinmek için Veri yazma ile ilgili en iyi uygulamalara göz atın.

Health Connect kimliklerini depolama

Uygulamanız Health Connect'ten de veri okuyorsa kayıtları ekleyip güncelledikten sonra Health Connect id değerini depolayın. Health Connect'ten veri değişikliklerini aldığınızda silme işlemlerini gerçekleştirmek için bu id gerekir.

insertRecords işlevi, id değerlerinin listesini içeren bir InsertRecordsResponse döndürür. Kayıt kimliklerini almak ve depolamak için yanıtı kullanın.

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

Health Connect'ten veri alma

Senkronizasyon işleminin ikinci bölümü, Health Connect'ten uygulamanızın veri deposuna veri değişikliklerini çekmektir. Veri değişiklikleri, güncellemeleri ve silme işlemlerini içerebilir.

Değişiklik jetonu alma

Uygulamanızın, Health Connect'ten alınacak değişikliklerin listesini almak için Değişiklikler jetonlarını takip etmesi gerekir. Hem veri değişikliklerinin listesini hem de bir sonraki sefer kullanılacak yeni bir Changes jetonunu döndürmek için Changes isteğinde bulunurken bunları kullanabilirsiniz.

Değişiklikler jetonu almak için getChangesToken yöntemini çağırın ve gerekli veri türlerini sağlayın.

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

Veri değişikliklerini kontrol etme

Changes jetonunu aldığınıza göre, tüm Changes'ı almak için bu jetonu kullanın. Mevcut veri değişiklikleri olup olmadığını kontrol ettiği tüm Değişiklikler'i incelemek için bir döngü oluşturmanızı öneririz. Aşağıdaki adımları uygulayın:

Değişiklikler listesini almak için jetonu kullanarak getChanges yöntemini çağırın.
Her değişikliğin türünün UpsertionChange mi yoksa DeletionChange mı olduğunu kontrol edin ve gerekli işlemleri yapın.
- UpsertionChange için, verileri yeniden içe aktarmadığınızdan emin olmak amacıyla yalnızca arama uygulamasından gelmeyen değişiklikleri alın.
Sonraki Değişiklikler jetonunu yeni jetonunuz olarak atayın.
Değişiklik kalmayana kadar 1-3 arasındaki adımları tekrarlayın.
Sonraki jetonu saklayın ve gelecekteki bir içe aktarma işlemi için ayırın.

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

Veri çekmeyle ilgili pratik konular hakkında bilgi edinmek için Verileri senkronize etme ile ilgili en iyi uygulamalara göz atın.

Süreç verilerindeki değişiklikler

Değişiklikleri uygulamanızın veri deposuna yansıtın. UpsertionChange için kaydı upsert etmek üzere id ve metadata içindeki lastModifiedTime değerini kullanın. DeletionChange için, kaydı silmek üzere sağlanan id kullanın. Bunun için kaydı id, Health Connect kimliklerini depolama bölümünde belirtildiği şekilde depolamış olmanız gerekir.

Health Connect'teki verileri silme

Bir kullanıcı kendi verilerini uygulamanızdan sildiğinde, verilerin Health Connect'ten de kaldırıldığından emin olun. Bunun için deleteRecords kullanın. Bu, bir kayıt türü ve id ile clientRecordId değerlerinin listesini alır. Bu sayede, birden fazla veriyi silmek için toplu işlem yapmak kolaylaşır. timeRangeFilter alan alternatif bir deleteRecords da mevcuttur.

Giyilebilir cihazlardan düşük gecikmeli senkronizasyon

Giyilebilir fitness cihazındaki verileri düşük gecikmeyle Health Connect'e senkronize etmek için CompanionDeviceService kullanın. Bu yaklaşım, BLE GATT bildirimlerini veya göstergelerini destekleyen ve Android 8.0 (API düzeyi 26) ya da sonraki sürümleri hedefleyen cihazlarda kullanılabilir. CompanionDeviceService, uygulamanızın giyilebilir cihazlardan veri almasına ve uygulama çalışmıyorken bile bu verileri Health Connect'e yazmasına olanak tanır. BLE ile ilgili en iyi uygulamalar hakkında daha fazla bilgi için Bluetooth Düşük Enerji'ye genel bakış başlıklı makaleyi inceleyin.

Cihazı ilişkilendirme

Öncelikle uygulamanız, CompanionDeviceManager kullanarak giyilebilir cihazı uygulamanızla ilişkilendirmek için kullanıcıya tek seferlik bir işlemde rehberlik etmelidir. Bu işlem, uygulamanıza cihazla etkileşim kurmak için gerekli izinleri verir. Daha fazla bilgi için Yardımcı cihaz eşleştirme başlıklı makaleyi inceleyin.

Hizmeti manifest dosyasında tanımlama

Ardından, uygulamanızın manifest dosyasında CompanionDeviceService iznini beyan edin. AndroidManifest.xml dosyanıza aşağıdakileri ekleyin:

<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 oluşturma

Son olarak, CompanionDeviceService sınıfını genişleten bir sınıf oluşturun. Bu hizmet, giyilebilir cihazla bağlantıyı yönetir ve BLE GATT geri çağırmaları aracılığıyla veri alır. Yeni veriler alındığında hemen Health Connect'e yazılır.

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

Veri senkronizasyonuyla ilgili en iyi uygulamalar

Aşağıdaki faktörler senkronizasyon sürecini etkiler.

Jetonun geçerlilik süresi

Kullanılmayan Changes jetonunun süresi 30 gün içinde dolduğundan, bu durumda bilgi kaybını önleyen bir senkronizasyon stratejisi kullanmanız gerekir. Stratejiniz aşağıdaki yaklaşımları içerebilir:

Uygulama veri deponuzda, Health Connect'ten id içeren en son kullanılan kaydı arayın.
Health Connect'ten belirli bir zaman damgasıyla başlayan kayıtları isteyin, ardından bunları uygulamanızın veri deposuna ekleyin veya güncelleyin.
Bir sonraki ihtiyaç duyulduğunda kullanmak üzere bir Değişiklikler jetonu isteyin.

Önerilen değişiklik yönetimi stratejileri

Uygulamanız geçersiz veya süresi dolmuş Değişiklikler jetonları alıyorsa mantığınızdaki uygulamasına bağlı olarak aşağıdaki yönetim stratejilerini öneririz:

Tüm verileri okuma ve tekilleştirme Bu en ideal stratejidir.
- Health Connect'ten en son veri okudukları zamanın zaman damgasını saklayın.
- Jetonun süresi dolduğunda, en son zaman damgasından itibaren veya son 30 güne ait tüm verileri yeniden okuyun. Ardından, tanımlayıcıları kullanarak daha önce okunan verilerle karşılaştırıp kopyaları kaldırın.
- Veri güncellemeleri için gerekli olduğundan istemci kimliklerini uygulamanız önerilir.
Yalnızca son okuma zaman damgasından sonraki verileri okuma. Bu durum, değişiklik jetonunun süresinin dolduğu zamanlarda bazı veri tutarsızlıklarına neden olur ancak bu süre daha kısadır ve birkaç saat ile birkaç gün arasında sürebilir.
- Health Connect'ten en son veri okudukları zamanın zaman damgasını saklayın.
- Jetonun süresi dolduğunda, bu zaman damgasından itibaren tüm verileri okuyun.
Son 30 güne ait verileri silip okuyun. Bu, ilk entegrasyonda gerçekleşenlerle daha uyumludur.
- Uygulamanın son 30 gün içinde Health Connect'ten okuduğu tüm verileri siler.
- Silindikten sonra tüm bu verileri tekrar okuyun.
Son 30 güne ait verileri tekilleştirmeden okuma. Bu, en az ideal olan stratejidir ve kullanıcılara yinelenen verilerin gösterilmesine neden olur.
- Uygulamanın son 30 gün içinde Health Connect'ten okuduğu tüm verileri siler.
- Yinelenen girişlere izin verilir.

Veri türü: Değişiklik jetonları

Uygulamanız birden fazla veri türünü bağımsız olarak kullanıyorsa her veri türü için ayrı Değişiklik Jetonları kullanın. Changes Sync API ile birden fazla veri türü içeren bir listeyi yalnızca bu veri türleri birlikte kullanılıyorsa veya hiç kullanılmıyorsa kullanın.

Ön plan okumaları

Uygulamalar yalnızca ön plandayken Health Connect'teki verileri okuyabilir. Health Connect'ten veri senkronizasyonu yapılırken Health Connect'e erişim herhangi bir noktada kesintiye uğrayabilir. Örneğin, uygulamanız Health Connect'ten büyük miktarda veri okurken senkronizasyonun ortasında kesintileri işlemeli ve uygulama bir sonraki açılışında devam etmelidir.

Arka planda okuma

Uygulamanızın arka planda çalışmasını ve Health Connect'teki verileri okumasını isteyebilirsiniz. Background Read izni isterseniz kullanıcınız, uygulamanıza arka planda veri okuma erişimi verebilir.

Zamanlamaları içe aktarma

Uygulamanız yeni verilerle ilgili bildirim alamayacağından, yeni verileri iki noktada kontrol edin:

Uygulamanız ön planda her etkinleştiğinde. Bu durumda yaşam döngüsü olaylarını kullanın.
Uygulamanız ön planda kaldığı sürece düzenli olarak. Yeni veriler kullanıma sunulduğunda kullanıcıları bilgilendirerek değişiklikleri yansıtmak için ekranlarını güncellemelerine olanak tanıyın.

Verileri silin

Meta veri gereksinimleri