Verileri yazma

Bu kılavuz, Health Connect'in 1.1.0-alpha12 sürümüyle uyumludur.

Bu kılavuzda, Health Connect'te veri yazma veya güncelleme süreci açıklanmaktadır.

Sıfır değerleri işleme

Adım, mesafe veya kalori gibi bazı veri türlerinin değeri 0 olabilir. Yalnızca kullanıcı cihazı takarken gerçek bir hareketsizliği yansıtıyorsa sıfır değerleri yazın. Cihaz takılmadıysa, veriler eksikse veya pil bittiyse sıfır değeri yazmayın. Bu gibi durumlarda, yanıltıcı verileri önlemek için kaydı atlayın.

Veri yapısını ayarlama

Veri yazmadan önce kayıtları ayarlamamız gerekir. 50'den fazla veri türü için her birinin kendi yapısı vardır. Kullanılabilen veri türleri hakkında daha fazla bilgi için Jetpack referansını inceleyin.

Temel kayıtlar

Health Connect'teki Adımlar veri türü, bir kullanıcının okumalar arasında attığı adım sayısını yakalar. Adım sayısı, sağlık, fitness ve sağlıklı yaşam platformlarında yaygın olarak kullanılan bir ölçümdür.

Aşağıdaki örnekte, adım sayısı verilerinin nasıl ayarlanacağı gösterilmektedir:

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)
    )
)

Ölçü birimleri içeren kayıtlar

Health Connect, doğruluğu sağlamak için değerleri ölçü birimleriyle birlikte saklayabilir. Buna bir örnek, geniş ve kapsamlı olan Beslenme veri türüdür. Toplam karbonhidratlardan vitaminlere kadar çeşitli isteğe bağlı besin alanları içerir. Her veri noktası, bir öğün veya yiyecek öğesi kapsamında tüketilmiş olabilecek besinleri temsil eder.

Bu veri türünde tüm besinler Mass birimleriyle, energy ise Energy birimiyle gösterilir.

Aşağıdaki örnekte, muz yiyen bir kullanıcı için beslenme verilerinin nasıl ayarlanacağı gösterilmektedir:

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)
    )
)

Seri verileri içeren kayıtlar

Health Connect, bir dizi verinin listesini saklayabilir. Örneğin, okumalar arasında tespit edilen bir dizi kalp atışı örneğini yakalayan nabız veri türü.

Bu veri türünde, samples parametresi bir nabız örnekleri listesiyle gösterilir. Her örnekte bir beatsPerMinute değeri ve bir time değeri bulunur.

Aşağıdaki örnekte, kalp atış hızı serisi verilerinin nasıl ayarlanacağı gösterilmektedir:

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)
    ))

Kullanıcıdan izin isteme

İstemci örneği oluşturduktan sonra uygulamanızın kullanıcıdan izin istemesi gerekir. Kullanıcıların izinleri istedikleri zaman vermesine veya reddetmesine izin verilmelidir.

Bunun için gerekli veri türleri için bir izin grubu oluşturun. Gruptaki izinlerin önce Android manifestinizde tanımlandığından emin olun.

// 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)
)

Uygulamanıza gerekli izinlerin verilip verilmediğini görmek için getGrantedPermissions aracını kullanın. Aksi takdirde, bu izinleri istemek için createRequestPermissionResultContract simgesini kullanın. Bu işlem, Health Connect izinleri ekranını gösterir.

// 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)
  }
}

Kullanıcılar izinleri istedikleri zaman verebilir veya iptal edebilir. Bu nedenle, uygulamanızın verilen izinleri düzenli olarak kontrol etmesi ve izinlerin kaybedildiği senaryoları yönetmesi gerekir.

Verileri yazma

Health Connect'teki yaygın iş akışlarından biri veri yazmadır. Kayıt eklemek için insertRecords uygulamasını kullanın.

Aşağıdaki örnekte, adım sayılarını ekleme verilerinin nasıl yazılacağı gösterilmektedir:

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
    }
}

Verileri güncelleme

Bir veya daha fazla kaydı değiştirmeniz gerekiyorsa (özellikle uygulama veri deponuzu Health Connect'teki verilerle senkronize etmeniz gerektiğinde) verilerinizi güncelleyebilirsiniz. Mevcut verileri güncellemenin iki yolu vardır. Bu yollar, kayıtları bulmak için kullanılan tanımlayıcıya bağlıdır.

Meta veri

Verileri güncellerken bu sınıfın kullanılması gerektiğinden öncelikle Metadata sınıfını incelemeniz önerilir. Oluşturulduğunda, Health Connect'teki her Record öğesinin bir metadata alanı olur. Aşağıdaki özellikler senkronizasyonla ilgilidir:

Okuma zaman aralığına göre güncelleme

Verileri güncellemek için önce gerekli kayıtları hazırlayın. Gerekirse kayıtlarda değişiklik yapın. Ardından, değişiklikleri yapmak için updateRecords numarasını arayın.

Aşağıdaki örnekte verilerin nasıl güncelleneceği gösterilmektedir. Bu amaçla, her kaydın saat dilimi farkı değerleri PST'ye göre ayarlanır.

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
    }
}

Müşteri kaydı kimliği aracılığıyla ekleme/güncelleme

İsteğe bağlı Müşteri Kaydı Kimliği ve Müşteri Kaydı Sürümü değerlerini kullanıyorsanız updateRecords yerine insertRecords kullanmanızı öneririz.

insertRecords işlevi, verileri ekleme veya güncelleme özelliğine sahiptir. Veriler, verilen istemci kaydı kimlikleri grubuna göre Health Connect'te varsa üzerine yazılır. Aksi takdirde yeni veri olarak yazılır. Bu senaryo, uygulama veri deponuzdaki verileri Health Connect ile senkronize etmeniz gerektiğinde kullanışlıdır.

Aşağıdaki örnekte, uygulama veri deposundan çekilen verilerde nasıl upsert işlemi yapılacağı gösterilmektedir:

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
    }
}

Ardından, bu işlevleri ana iş parçacığınızda çağırabilirsiniz.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Müşteri Kaydı Sürümünde değer kontrolü

Veri ekleme veya güncelleme sürecinizde İstemci Kaydı Sürümü yer alıyorsa Health Connect, clientRecordVersion değerlerinde karşılaştırma kontrolleri gerçekleştirir. Eklenen verilerdeki sürüm, mevcut verilerdeki sürümden yüksekse upsert işlemi gerçekleşir. Aksi takdirde, işlem değişikliği yoksayar ve değer aynı kalır.

Verilerinize sürüm oluşturmayı dahil etmek için sürüm oluşturma mantığınıza göre Metadata.clientRecordVersion ile Long değeri sağlamanız gerekir.

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)
    )
)

Ekleme/güncellemeler, değişiklik olduğunda version değerini otomatik olarak artırmaz. Bu sayede, verilerin beklenmedik şekilde üzerine yazılması önlenir. Bu durumda, daha yüksek bir değerle manuel olarak sağlamanız gerekir.

Veri yazmayla ilgili en iyi uygulamalar

Uygulamalar, Health Connect'e yalnızca kendi kaynaklı verileri yazmalıdır.

Uygulamanızdaki veriler başka bir uygulamadan içe aktarıldıysa bu verilerin Health Connect'e yazılması sorumluluğu diğer uygulamaya aittir.

Ayrıca, verilerin sınırların dışında olması veya dahili sistem hatası gibi yazma istisnalarını işleyen bir mantık uygulamak da iyi bir fikirdir. Geri çekilme ve yeniden deneme stratejilerinizi bir iş planlama mekanizmasına uygulayabilirsiniz. Health Connect'e yazma işlemi başarısız olursa uygulamanızın bu dışa aktarma noktasını geçebildiğinden emin olun. Teşhise yardımcı olmak için hataları günlüğe kaydetmeyi ve bildirmeyi unutmayın.

Verileri izlerken, uygulamanızın verileri yazma şekline bağlı olarak uygulayabileceğiniz birkaç öneri vardır.

Saat dilimi işleme

Zamana dayalı kayıtlar yazarken, kullanıcılar başka bölgelerdeyken yanlış zaman damgalarına yol açabileceğinden, varsayılan olarak zoneOffset.UTC için ofset ayarlamaktan kaçının. Bunun yerine, cihazın gerçek konumuna göre uzaklığı hesaplayın. Cihazın saat dilimini ZoneId.systemDefault() kullanarak alabilirsiniz.

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
)

Daha fazla ayrıntı için ZoneId ile ilgili dokümanları inceleyin.

Pasif izleme

Arka planda sürekli olarak adım sayısını veya kalp atış hızını kaydetme gibi pasif fitness ya da sağlık takibi yapan uygulamalar bu kapsamdadır.

Uygulamanızın, aşağıdaki yöntemlerle Health Connect'e düzenli olarak veri yazması gerekir:

• Her senkronizasyonda yalnızca yeni verileri ve son senkronizasyondan bu yana değiştirilen güncellenmiş verileri yazın.
• Yazma isteği başına en fazla 1.000 kayıt olacak şekilde istekleri parçalayın.
• En az 15 dakikalık bir süreyle düzenli arka plan görevleri planlamak için WorkManager'ı kullanın.
• Görevlerin yalnızca cihaz boşta kaldığında ve pil seviyesi düşük olmadığında çalışmasını sağlayın.

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

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

Etkin izleme

Egzersiz ve uyku gibi etkinliğe dayalı izleme veya beslenme gibi manuel kullanıcı girişi yapan uygulamalar bu kapsamdadır. Bu kayıtlar, uygulama ön plandayken veya nadir durumlarda, günde birkaç kez kullanıldığında oluşturulur.

Uygulamanızın, Health Connect'i etkinliğin tamamı boyunca çalıştırmadığından emin olun.

Veriler Health Connect'e iki şekilde yazılabilir:

• Etkinlik tamamlandıktan sonra verileri Health Connect ile senkronize edin. Örneğin, kullanıcı izlenen bir egzersiz oturumunu sonlandırdığında verileri senkronize edin.
• Verileri daha sonra senkronize etmek için WorkManager kullanarak tek seferlik bir görev planlayın.

Yazma işlemlerinin ayrıntı düzeyi ve sıklığıyla ilgili en iyi uygulamalar

Health Connect'e veri yazarken uygun çözünürlüğü kullanın. Uygun çözünürlüğü kullanmak, tutarlı ve doğru verileri korurken depolama yükünü azaltmaya yardımcı olur. Veri çözünürlüğü 2 şeyi kapsar:

1. Yazma sıklığı: Uygulamanızın Health Connect'e yeni veri gönderme sıklığı. Örneğin, her 15 dakikada bir yeni veri yazın.
2. Yazılan verilerin ayrıntı düzeyi: Gönderilen verilerin ne sıklıkta örneklenmiş olduğu. Örneğin, her 5 saniyede bir nabız örneği yazın. Her veri türü aynı örnekleme hızını gerektirmez. Adım sayısı verilerini 60 saniyede bir gibi daha az sıklıkta güncellemek yerine her saniye güncellemenin pek bir faydası yoktur. Ancak daha yüksek örnekleme hızları, kullanıcılara sağlık ve fitness verileriyle ilgili daha ayrıntılı ve ayrıntılı bir görünüm sunabilir. Örnekleme hızı frekansları, ayrıntı ve performans arasında bir denge kurmalıdır.

Gün boyunca izlenen verileri yazma

Adım sayısı gibi sürekli olarak toplanan veriler için uygulamanız gün içinde en az 15 dakikada bir Health Connect'e yazmalıdır.

Yazma oturumları

Veriler, egzersiz veya uyku oturumunun sonunda Health Connect'e yazılmalıdır.

Uygulamanız en azından aşağıdaki tablodaki beklenen sütunundaki yönergelere uymalıdır. Mümkün olduğunda en iyi rehberliği uygulayın.

Egzersiz ve uyku oturumları

Aşağıdaki örnekte, egzersiz sırasında verilerin nasıl yazılacağı gösterilmektedir:

Aşağıdaki örnekte, uyku seansı sırasında veya sonrasında verilerin nasıl yazılacağı gösterilmektedir:

Çoklu spor etkinlikleri

Bu yaklaşımda mevcut veri türleri ve yapılar kullanılır. Ayrıca, mevcut Health Connect uygulamaları ve veri okuyucularıyla uyumluluk doğrulanır. Bu, fitness platformlarının yaygın olarak kullandığı bir yaklaşımdır.

Aşağıdaki örnekte, triatlon için verilerin nasıl yazılacağı gösterilmektedir:

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))