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çü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ğ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 örnekleri listesi ile 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)
))
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 yeni ekleme 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ı kaydeden gibi pasif fitness veya sağlık izleme 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 süreyle 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:
- 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.
- Yazılan 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 saniye gibi daha seyrek bir ritim yerine her saniye güncellemenin çok fazla faydası yoktur. 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 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.
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 |
Her 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 Atışı 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 |