Verileri yazma

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

Bu kılavuzda, Health Connect'te veri yazma veya güncelleme süreci ele alınmaktadır.

Veri yapısını ayarlama

Verileri yazmadan önce kayıtları oluşturmamı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ü, kullanıcının ölçümler arasında attığı adım sayısını yakalar. Adım sayıları, sağlık, fitness ve sağlıklı yaşam platformlarında ortak bir ölçümü temsil eder.

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ğruluk sağlamak için değerleri ölçü birimleriyle birlikte saklayabilir. Geniş ve kapsamlı Beslenme veri türü buna örnek gösterilebilir. Toplam karbonhidratlardan vitaminlere kadar çeşitli isteğe bağlı besin alanları içerir. Her veri noktası, bir öğün veya gıda maddesi kapsamında tüketilebilecek besinleri temsil eder.

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

Aşağıdaki örnekte, muz yiyen bir kullanıcının 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, seri verilerinin bir listesini saklayabilir. Örneğin, ölçümler arasında algılanan bir dizi kalp atışı örneğini yakalayan Nabız veri türü.

Bu veri türünde samples parametresi, nabız örneklerinin listesiyle temsil edilir. Her örnek bir beatsPerMinute değeri ve bir time değeri içerir.

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

Uygulamanızın, istemci örneği oluşturduktan sonra kullanıcıdan izin istemesi gerekir. Kullanıcıların diledikleri zaman izin vermesine veya reddetmesine izin verilmelidir.

Bunun için gerekli veri türleri için bir dizi izin oluşturun. Öncelikle, gruptaki izinlerin Android manifest dosyanızda beyan edildiğinden 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'u kullanın. Aksi takdirde bu izinleri istemek için createRequestPermissionResultContract değerini kullanın. Health Connect izinleri ekranı gösterilir.

// 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 verip iptal edebileceğinden, uygulamanızın izinleri düzenli olarak kontrol etmesi ve iznin kaybedildiği senaryoları ele alması gerekir.

Verileri yazma

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

Aşağıdaki örnekte, veri ekleme adım sayılarının 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 yöntemler, kayıtları bulmak için kullanılan tanımlayıcıya bağlıdır.

Meta veri

Verileri güncellerken gerekli olduğu için önce Metadata sınıfını incelemeniz önerilir. Health Connect'te oluşturulan her Record'in bir metadata alanı vardır. Aşağıdaki özellikler senkronizasyonla ilgilidir:

Özellikler Açıklama
id Health Connect'teki her Record, benzersiz bir id değerine sahiptir.
Health Connect, yeni bir kayıt eklerken bu alanı otomatik olarak doldurur.
lastModifiedTime Her Record, kaydın en son değiştirildiği zamanı da izler.
Health Connect bu alanı otomatik olarak doldurur.
clientRecordId Her Record, uygulama veri deposunuzda referans olarak kullanılacak benzersiz bir kimliğe sahip olabilir.
Bu değeri uygulamanız sağlar.
clientRecordVersion Bir kayıtta clientRecordId varsa verilerin uygulama veri ambarınızdaki sürümle senkronize kalmasını sağlamak için clientRecordVersion kullanılabilir.
Bu değeri uygulamanız sağlar.

Kayıt kimliği üzerinden güncelleme

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

Aşağıdaki örnekte verilerin nasıl güncelleneceği gösterilmektedir. Bu amaçla, her kaydın bölge ofset değerleri PST'ye 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
    }
}

İstemci Kaydı Kimliği ile Upsert

İ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 güncelleme özelliğine sahiptir. Belirtilen istemci kaydı kimlikleri grubuna göre Health Connect'te mevcut olan verilerin ü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 alınan verilerde nasıl bir 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 mesaj dizinizde çağırabilirsiniz.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

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

Veri ekleme işleminiz Müşteri Kaydı Sürümü'nü içeriyorsa Health Connect, clientRecordVersion değerlerindeki karşılaştırma kontrollerini gerçekleştirir. Eklenen verilerin sürümü, mevcut verilerin sürümünden daha yüksekse yenileme işlemi gerçekleşir. Aksi takdirde, işlem değişikliği yoksayar ve değer aynı kalır.

Verilerinize sürüm kontrolünü dahil etmek için Metadata.clientRecordVersion değerine sürüm kontrol mantığınıza göre bir Long değeri göndermeniz 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)
    )
)

Upsert'ler, değişiklik olduğunda version değerini otomatik olarak artırmaz. Bu sayede, verilerin beklenmedik bir şekilde üzerine yazılmasını önler. Bu durumda, manuel olarak daha yüksek bir değer sağlamanız gerekir.

Veri yazmayla ilgili en iyi uygulamalar

Uygulamalar Health Connect'e yalnızca kendi kaynaklarından gelen verileri yazmalıdır.

Uygulamanızdaki veriler başka bir uygulamadan içe aktarıldıysa kendi verilerini Health Connect'e yazma sorumluluğu diğer uygulamaya aittir.

Verilerin sınırların dışında olması veya dahili bir sistem hatası gibi yazma istisnalarını ele alan 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 sonunda başarısız olursa uygulamanızın bu dışa aktarma noktasını geçebildiğinden emin olun. Teşhis sürecine 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.

Pasif izleme

Arka planda sürekli olarak adım sayısını veya nabzınızı kaydeden gibi pasif fitness veya sağlık takibi yapan uygulamalar da buna dahildir.

Uygulamanızın, Health Connect'e aşağıdaki yöntemlerle 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çalara ayırın.
  • En az 15 dakikalık bir zaman aralığıyla düzenli arka plan görevleri planlamak için WorkManager simgesini kullanın.

  • Görevlerin yalnızca cihaz boştayken ve pil seviyesi düşük değilken çalışmasını kısıtlayı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 etkinliklere dayalı izleme yapan veya beslenme gibi manuel kullanıcı girişi gerektiren uygulamalar da buna dahildir. Bu kayıtlar, uygulama ön plandayken veya günde birkaç kez kullanıldığı nadir durumlarda oluşturulur.

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

Veriler Health Connect'e şu iki yöntemden biriyle yazılmalıdır:

  • 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.

Ayrıntı düzeyi ve yazma 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 alanındaki yükü azaltmaya yardımcı olur. Veri çözünürlüğü 2 şeyi kapsar:

  1. Yazma sıklığı: Uygulamanızın yeni verileri Health Connect'e ne sıklıkta gönderdiği. Örneğin, her 15 dakikada bir yeni veri yazın.
  2. Yazılı verilerin ayrıntı düzeyi: İçeri aktarılan verilerin ne sıklıkta örneklendiği. Örneğin, 5 saniyede bir nabız örnekleri yazın. Her veri türü için aynı örnekleme hızı gerekmez. Adım sayısı verilerini 60 saniyede bir gibi daha seyrek bir ritimde güncellemenin, saniyede bir güncellemekten çok az faydası vardır. Ancak daha yüksek örnekleme hızları, kullanıcıların sağlık ve fitness verilerine daha ayrıntılı ve ayrıntılı bir şekilde bakmasını sağlayabilir. Örnekleme hızı frekansları, ayrıntı ve performans arasında denge kurmalıdır.

Gün boyunca izlenen verileri yazma

Sürekli olarak toplanan veriler (ör. adımlar) için uygulamanız gün içinde en az 15 dakikada bir Health Connect'e yazmalıdır.

Veri türü

Birim

Beklenen

Örnek

Adımlar

adım

Dakikada bir

23:14 - 23:15 - 5 adım

23:16 - 23:17 - 22 adım

23:17 - 23:18 - 8 adım

StepsCadence

adım/dk.

Dakikada bir

23:14 - 23:15 - 5 spm

23:16 - 23:17 - 22 spm

23:17 - 23:18 - 8 spm

Tekerlekli sandalye itme sayısı

itme

Dakikada bir

23:14 - 23:15 - 5 itme

23:16 - 23:17 - 22 itme

23:17 - 23:18 - 8 itme

ActiveCaloriesBurned

Kalori

15 dakikada bir

23:15 - 23:30 - 2 Kalori

23:30 - 23:45 - 25 Kalori

23:45 - 00:00 - 5 Kalori

TotalCaloriesBurned

Kalori

15 dakikada bir

23:15 - 23:30 - 16 Kalori

23:30 - 23:45 - 16 Kalori

23:45 - 00:00 - 16 Kalori

Mesafe

km/dk.

Dakikada bir

23:14-23:15 - 0,008 km

23:16 - 23:16 - 0,021 km

23:17 - 23:18 - 0,012 km

ElevationGained

m

Dakikada bir

20:36 - 20:37 - 3.048m

20:39 - 20:40 - 3.048m

23:23 - 23:24 - 9.144m

FloorsClimbed

kat

Dakikada bir

23:14 - 23:15 - 5 kat

23:16 - 23:16 - 22 kat

23:17 - 23:18 - 8 kat

HeartRate

nabız/dk

Dakikada bir

06:11 - 55 bpm

HeartRateVariabilityRmssd

ms

Dakikada bir

06:11 - 23 ms

RespiratoryRate

nefes/dakika

Dakikada bir

23:14 - 23:15 - 60 nefes/dakika

23:16 - 23:16 - 62 nefes/dakika

23:17 - 23:18 - 64 nefes/dakika

OxygenSaturation

%

Saatte bir

6:11 - %95,208

Yazma oturumları

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

En iyi uygulama olarak, uyku veya egzersiz seansları, kayıt cihazı ve RecordingMethod dahil olmak üzere uygun meta verilerle birlikte yazılmalıdır.

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

Egzersiz sırasında izlenen veriler

Veri türü

Birim

Beklenen

Saygılarımızla,

Örnek

Adımlar

adım

Dakikada bir

1 saniyede bir

23:14-23:15 - 5 adım

23:16 - 23:17 - 22 adım

23:17 - 23:18 - 8 adım

StepsCadence

adım/dk.

Dakikada bir

1 saniyede bir

23:14-23:15 - 35 spm

23:16 - 23:17 - 37 spm

23:17 - 23:18 - 40 spm

Tekerlekli sandalye itme sayısı

itme

Dakikada bir

1 saniyede bir

23:14-23:15 - 5 itme

23:16 - 23:17 - 22 itme

23:17 - 23:18 - 8 itme

CyclingPedalingCadence

nefes/dk.

Dakikada bir

1 saniyede bir

23:14-23:15 - 65 devir/dk.

23:16 - 23:17 - 70 devir/dk.

23:17 - 23:18 - 68 devir/dk.

Güç

vat

Dakikada bir

1 saniyede bir

23:14-23:15 - 250 watt

23:16 - 23:17 - 255 vat

23:17 - 23:18 - 245 watt

Hız

km/dk.

Dakikada bir

1 saniyede bir

23:14-23:15 - 0,3 km/dk.

23:16 - 23:17 - 0,4 km/dk.

23:17 - 23:18 -0,4 km/dk.

Mesafe

km/m

Dakikada bir

1 saniyede bir

23:14-23:15 - 0,008 km

23:16 - 23:16 - 0,021 km

23:17 - 23:18 - 0,012 km

ActiveCaloriesBurned

Kalori

Dakikada bir

1 saniyede bir

23:14-23:15 - 20 Kalori

23:16 - 23:17 - 20 Kalori

23:17 - 23:18 - 25 Kalori

TotalCaloriesBurned

Kalori

Dakikada bir

1 saniyede bir

23:14-23:15 - 36 Kalori

23:16 - 23:17 - 36 Kalori

23:17 - 23:18 - 41 Kalori

ElevationGained

m

Dakikada bir

1 saniyede bir

20:36 - 20:37 - 3.048m

20:39 - 20:40 - 3.048m

23:23 - 23:24 - 9.144m

ExerciseRoutes

enl/boyl/alt

3-5 saniyede bir

1 saniyede bir

HeartRate

nabız/dk

Dakikada bir

1 saniyede bir

23:14-23:15 - 150 nabız/dk

23:16 - 23:17 -152 bpm

23:17 - 23:18 - 155 nabız/dk.

Uyku sırasında izlenen veriler

Veri türü

Birim

Beklenen örnekler

Örnek

Uyku Aşamaları

aşama

Uyku aşaması başına ayrıntılı zaman aralığı

23:46 - 23:50 - uyanık

23:50 - 23:56 - hafif uyku

23:56 - 00:16 - derin uyku

Dinlenme Kalp Hızı

nabız/dk

Tek günlük değer (sabah ilk iş olarak gönderilmesi beklenir)

06:11 - 60 bpm

OxygenSaturation

%

Tek günlük değer (sabah ilk iş olarak gönderilmesi beklenir)

6:11 - %95,208