Health Connect ile uyku deneyimleri geliştirme

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

Uygulamanızda uyku izleme deneyimi oluşturmak istiyorsanız Health Connect'i kullanarak aşağıdaki gibi işlemler yapabilirsiniz:

• Uyku seanslarını yazma
• Uyku aşaması verilerini yazma
• Nabız, oksijen doygunluğu ve solunum hızı gibi uyku verilerini yazma
• Diğer uygulamalardaki uyku verilerini okuma

Bu kılavuzda, veri türleri, arka planda yürütme, izinler, önerilen iş akışları ve en iyi uygulamalar dahil olmak üzere bu uyku özelliklerinin nasıl oluşturulacağı açıklanmaktadır.

Genel bakış: Kapsamlı bir uyku takip uygulaması oluşturma

Aşağıdaki temel adımları uygulayarak Health Connect ile kapsamlı bir uyku izleme deneyimi oluşturabilirsiniz:

• Sağlık İzinleri'ne dayalı izinleri doğru şekilde uygulama
• SleepSessionRecord kullanarak oturumları kaydetme.
• Oturum sırasında uyku aşamaları, nabız ve oksijen doygunluğu gibi veri türlerini tutarlı bir şekilde yazma.
• Gece boyunca sürekli veri yakalamayı doğrulamak için arka planda yürütmeyi doğru şekilde yönetme
• Uyku sonrası özetler ve analizler için oturum verileri okunuyor.

Bu iş akışı, diğer Health Connect uygulamalarıyla birlikte çalışabilirliği sağlar ve kullanıcı tarafından kontrol edilen veri erişimini doğrular.

Başlamadan önce

Uyku özelliklerini uygulamadan önce:

• Uygun bağımlılığı kullanarak Health Connect'i entegre edin.
• HealthConnectClient örneği oluşturun.
• Uygulamanızın, Sağlık İzinleri'ne dayalı çalışma zamanında istenen izin akışlarını uyguladığını doğrulayın.

Temel kavramlar

Health Connect, uyku verilerini birkaç temel bileşen kullanarak gösterir. SleepSessionRecord, uyku için merkezi kayıt görevi görür ve başlangıç veya bitiş zamanları ile uyku aşamaları gibi ayrıntıları içerir. Bir oturum sırasında HeartRateRecord veya OxygenSaturationRecord gibi çeşitli veri türleri kaydedilebilir.

Uyku seansları

Uyku verileri SleepSessionRecord ile temsil edilir. Her kayıt şunları depolar:

• startTime
• endTime
• stages: Derin, hafif, REM ve uyanık uyku dahil olmak üzere SleepSessionRecord.Stage listesi.
• İsteğe bağlı oturum meta verileri (başlık, notlar)

Uygulamalar, bir oturumla ilişkili birden fazla veri türü yazabilir.

Veri türleri

Uyku seansı sırasında kaydedilen yaygın veri türleri şunlardır:

• SleepSessionRecord: Derin, hafif, REM ve uyanık uyku dahil olmak üzere uyku süresini ve aşamalarını kaydeder.
• HeartRateRecord: Uyku sırasında nabzı kaydeder.
• OxygenSaturationRecord: Uyku sırasında oksijen doygunluğunu (SpO2) kaydeder.
• RespiratoryRateRecord: Uyku sırasında solunum hızını kaydeder.

Her veri türü ayrı bir kayıt olarak depolanır.

Geliştirme ile ilgili dikkat edilmesi gereken noktalar

Uyku izleme uygulamalarının genellikle uzun süreler boyunca, ekran kapalıyken arka planda çalışması gerekir. Uyku özelliklerinizi oluştururken arka planda yürütmeyi nasıl yöneteceğinizi düşünmeniz ve uyku verileri için gerekli izinleri istemeniz önemlidir.

Arka planda yürütme

Uyku izleme uygulamaları genellikle gece boyunca ekran kapalıyken çalışır. Bu durumdayken şunları kullanmanız gerekir:

• Veri toplama için ön plan hizmetleri
• Ertelenen yazma veya senkronizasyon için WorkManager
• Nabız gibi ayrıntılı verilerin düzenli kayıt yazma işlemleri için toplu iş stratejileri

Oturum kimliğini tüm yazma işlemlerinde tutarlı tutarak sürekliliği sağlayın.

İzinler

Uygulamanız, uyku verilerini okumadan veya yazmadan önce ilgili Health Connect izinlerini istemelidir. Veri türlerinin tam listesi için Health Connect veri türleri başlıklı makaleyi inceleyin. Uyku için yaygın izinler arasında uyku oturumları ve nabız ya da oksijen doygunluğu gibi metrikler yer alır.

Uyku verilerine erişim aşağıdaki izinlerle korunur:

• android.permission.health.READ_SLEEP
• android.permission.health.WRITE_SLEEP

Uygulamanıza uyku özelliğini eklemek için öncelikle SleepSession veri türü için izin isteyin.

Uyku verilerini yazabilmek için beyan etmeniz gereken izin şudur:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_SLEEP" />
...
</application>

Uyku verilerini okumak için aşağıdaki izinleri istemeniz gerekir:

<application>
  <uses-permission
android:name="android.permission.health.READ_SLEEP" />
...
</application>

Aşağıda, nabız, oksijen doygunluğu ve solunum hızı verilerini içeren bir uyku seansı için izin isteme örneği gösterilmektedir:

Uygulamanız, istemci örneği oluşturduktan sonra kullanıcıdan izin istemelidir. Kullanıcıların diledikleri zaman izin vermelerine veya izinleri reddetmelerine olanak tanınmalıdır. Bunun için gerekli veri türlerine yönelik bir izin grubu oluşturun. Öncelikle, kümedeki izinlerin Android manifest dosyanızda beyan edildiğinden emin olun.

val permissions =
    setOf(
        HealthPermission.getReadPermission(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(OxygenSaturationRecord::class),
        HealthPermission.getWritePermission(OxygenSaturationRecord::class),
        HealthPermission.getReadPermission(RespiratoryRateRecord::class),
        HealthPermission.getWritePermission(RespiratoryRateRecord::class)
    )
HealthConnectManager.kt

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
HealthConnectActivity.kt

Uyku seansı uygulama

Bu bölümde, uyku verilerini kaydetmek için önerilen iş akışı açıklanmaktadır.

HeartRateRecord veya OxygenSaturationRecord gibi veri türlerini bir uyku seansıyla uyumlu hale getirmek için bunları oturumun startTime ve endTime değerleri arasında kalan zaman damgalarıyla kaydedin. Health Connect, uyku oturumlarını ayrıntılı verilerle bağlamak için oturum tanımlayıcı kullanmaz. Bunun yerine, ilişkilendirme, çakışan zaman aralıkları aracılığıyla dolaylı olarak yapılır. Uyku verilerini okurken Uyku verilerini okuma bölümünde gösterildiği gibi, ilişkili veri türlerini sorgulamak için bir oturumun zaman aralığını kullanabilirsiniz.

Oturum yazma

Nabız gibi ayrıntılı veriler uyku oturumu boyunca kaydedilebilir ancak SleepSessionRecord, oturum bittikten sonra (ör. kullanıcı uyandığında) Health Connect'e yazılmalıdır. Kayıt, oturum startTime, endTime ve oturum sırasında kaydedilen SleepSessionRecord.Stage nesnelerinin listesini içermelidir. SleepSessionRecord, endTime değerinin startTime değerinden sonra olmasını gerektirir.

Uyku seansı yazmak için:

1. Benzersiz bir istemci kaydı kimliği oluşturun.
2. Kullanıcı uyandığında veya uyku izleme durdurulduğunda tüm uyku aşamalarını toplayıp bir SleepSessionRecord oluşturun.
3. insertRecords kullanarak kaydı ekleyin.

Örnek:

val clientRecordId = UUID.randomUUID().toString()
val sessionStartTime = LocalDateTime.of(2023, 10, 30, 22, 0).toInstant(ZoneOffset.UTC)
val sessionEndTime = LocalDateTime.of(2023, 10, 31, 7, 0).toInstant(ZoneOffset.UTC)

val stages = mutableListOf<SleepSessionRecord.Stage>()
// Add recorded stages, for example:
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(3600),
    endTime = sessionStartTime.plusSeconds(7200),
    stage = SleepSessionRecord.STAGE_TYPE_LIGHT)
)
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(7200),
    endTime = sessionStartTime.plusSeconds(10800),
    stage = SleepSessionRecord.STAGE_TYPE_DEEP)
)
// ... other stages

val session = SleepSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    stages = stages,
    metadata = Metadata(clientRecordId = clientRecordId)
)

healthConnectClient.insertRecords(listOf(session))

Uyku verileri okunuyor

Uygulamalar, aktiviteyi özetlemek, sağlıkla ilgili analizler sunmak veya verileri harici bir sunucuyla senkronize etmek için uyku oturumlarını ve bunlarla ilişkili verileri okuyabilir. Örneğin, bir SleepSessionRecord okuyabilir ve ardından aynı zaman aralığında gerçekleşen HeartRateRecord sorgulayabilirsiniz.

İlişkili verilerle oturumu okuma

Kayıt türü SleepSessionRecord olan bir ReadRecordsRequest kullanarak uyku oturumlarını okuyabilir ve bunları bir zaman aralığına göre filtreleyebilirsiniz. Belirli bir oturumla ilişkili verileri okumak için seçilen veri türü (ör. HeartRateRecord) için ikinci bir istekte bulunun. Bu istekte, uyku seansının startTime ve endTime değerlerine göre filtreleme yapın.

Aşağıdaki örnekte, belirli bir zaman aralığı için ilişkili nabız verileriyle uyku seanslarının nasıl okunacağı gösterilmektedir:

suspend fun readSleepSessionsWithAssociatedData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = SleepSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (sleepRecord in response.records) {
        // Process each session
        val stages = sleepRecord.stages
        val notes = sleepRecord.notes

        // To read specific granular data (like heart rate) that occurred during
        // this session, use the session's startTime and endTime to filter
        // the request for that data type.
        val hrResponse = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    sleepRecord.startTime,
                    sleepRecord.endTime
                )
            )
        )
        for (heartRateRecord in hrResponse.records) {
            for (sample in heartRateRecord.samples) {
                val bpm = sample.beatsPerMinute
            }
        }
    }
}

En iyi uygulamalar

Veri güvenilirliğini ve kullanıcı deneyimini iyileştirmek için aşağıdaki yönergeleri uygulayın:

• Aktif izleme sırasında sık sık yazma: Aktif izleme için verileri kullanılabilir olduğunda veya maksimum 15 dakikalık aralıklarla yazın.
• Arka plan senkronizasyonları için WorkManager'ı kullanın: Ertelenen yazma işlemleri için WorkManager kullanın. Gerçek zamanlı veriler ile pil verimliliği arasında denge kurmak için 15 dakikalık bir aralık hedefleyin.
• Yazma isteklerini toplu olarak gönderin: Her sensör etkinliğini ayrı ayrı yazmayın. İsteklerinizi parçalara ayırın. Health Connect, yazma isteği başına en fazla 1.000 kayıt işler.
• Oturum kimliklerini sabit ve benzersiz tutun: Oturumlarınız için tutarlı tanımlayıcılar kullanın. Bir oturum düzenlenir veya güncellenirse aynı kimliğin kullanılması, oturumun yeni ve ayrı bir oturum olarak değerlendirilmesini önler.
• Veri türleri için toplu işlem kullanın: Giriş/çıkış ek yükünü azaltmak ve pil ömrünü korumak için veri noktalarınızı tek tek yazmak yerine tek bir insertRecords çağrısında gruplandırın.
• Yinelenen veriler yazmaktan kaçınma: İstemci kimliklerini kullanma: Kayıt oluştururken metadata.clientRecordId ayarlayın. Health Connect, benzersiz kayıtları tanımlamak için bu bilgiyi kullanır. Zaten mevcut olan bir clientRecordId ile kayıt yazmaya çalışırsanız Health Connect, yeni bir kayıt oluşturmak yerine kopyayı yok sayar veya mevcut kaydı günceller. metadata.clientRecordId ayarlamak, senkronizasyon yeniden denemeleri veya uygulamanın yeniden yüklenmesi sırasında yinelenenleri önlemenin en etkili yoludur.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• Mevcut verileri kontrol etme: Senkronizasyondan önce, uygulamanızdaki kayıtların zaten mevcut olup olmadığını görmek için zaman aralığını sorgulayın.
• Zaman damgalarının çakışmadığından emin olun: Yeni bir oturumun, önceki oturum sona ermeden başlamadığını doğrulayın. Çakışan oturumlar, fitness kontrol panellerinde ve özet hesaplamalarında çakışmalara neden olabilir.
• İzin için net gerekçeler sunun: Uygulamanızın sağlık verilerine neden erişmesi gerektiğini açıklamak için Permission.createIntent akışını kullanın. Örneğin: "Tansiyonunuzda gözlemlenen değişimleri izlemek ve analizler sunmak için."
• Uzun süreli oturumları test edin: Birkaç saat süren oturumlar sırasında pil tüketimini izleyerek toplu iş aralığınızın ve sensör kullanımınızın cihazı tüketmediğini doğrulayın.
• Zaman damgalarını sensör hızlarıyla hizalama: Verilerin yüksek doğruluğunu korumak için kayıt zaman damgalarınızı sensörlerinizin gerçek frekansıyla eşleştirin.

Test

Verilerin doğruluğunu ve yüksek kaliteli bir kullanıcı deneyimini doğrulamak için bu test stratejilerini uygulayın ve resmi En önemli kullanım alanlarını test etme belgelerine bakın.

Doğrulama araçları

• Health Connect Araç Kutusu: Kayıtları manuel olarak incelemek, test verilerini silmek ve veritabanındaki değişiklikleri simüle etmek için bu tamamlayıcı uygulamayı kullanın. Kayıtlarınızın doğru şekilde saklandığını doğrulamanın en iyi yolu budur.
• FakeHealthConnectClient ile birim testi: Uygulamanızın, izin iptali veya API istisnaları gibi uç durumları fiziksel bir cihaza ihtiyaç duymadan nasıl işlediğini doğrulamak için test kitaplığını kullanın.

Kalite kontrol listesi

Tipik mimari

Uyku izleme uygulaması genellikle şunları içerir:

Sorun giderme

Sık kullanılan hata ayıklama adımları