Health Connect ile uyku deneyimleri geliştirme

Uygulamanızda uyku izleme deneyimi oluşturmak istiyorsanız Health Connect'i kullanarak şunları yapabilirsiniz:

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

Bu kılavuzda, uyku özelliklerinin nasıl oluşturulacağı açıklanmakta ve veri türleri, arka planda yürütme, izinler, önerilen iş akışları ve en iyi uygulamalar ele alınmaktadır.

Genel bakış: Kapsamlı bir uyku izleyici oluşturma

Şu temel adımları uygulayarak Health Connect'i kullanarak kapsamlı bir uyku izleme deneyimi oluşturabilirsiniz:

• Sağlık İzinleri'ne göre izinlerin doğru şekilde uygulanması.
• SleepSessionRecord kullanılarak kaydedilen oturumlar.
• Oturum sırasında uyku aşamaları, nabız ve oksijen doygunluğu gibi veri türlerini tutarlı bir şekilde yazma.
• Gece boyunca kesintisiz veri yakalamayı doğrulamak için arka planda yürütmeyi düzgün şekilde yönetme.
• Uyku sonrası özetler ve analizler için oturum verilerini okuma

Bu iş akışı, diğer Health Connect uygulamalarıyla birlikte çalışabilmeyi sağlar ve kullanıcı kontrollü 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, çalışma zamanı izin akışlarını Sağlık İzinleri'ne göre uyguladığını doğrulayın.

Temel kavramlar

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

Uyku seansları

Uyku verileri SleepSessionRecord ile gösterilir. Her kayıt şu bilgileri saklar:

• 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ındaki 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 hususlar

Uyku izleme uygulamalarının genellikle uzun süre çalışması gerekir. Bu uygulamalar, ekran kapalıyken sıklıkla arka planda çalışır. Uyku özelliklerinizi oluştururken arka planda yürütmeyi nasıl yöneteceğinizi ve uyku verileri için gerekli izinleri nasıl isteyeceğinizi göz önünde bulundurmanız önemlidir.

Arka planda yürütme

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

• Veri toplama için ön plan hizmetleri
• WorkManager ertelenmiş yazma veya senkronizasyon için
• Kalp atış hızı gibi ayrıntılı verilerin düzenli olarak yazılması için toplu işleme stratejileri

Tüm yazma işlemlerinde oturum kimliğini tutarlı tutarak sürekliliği koruyun.

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

Uykuya erişim aşağıdaki izinlerle korunur:

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

Uygulamanıza uyku özelliği eklemek için öncelikle SleepSession veri türüyle ilgili izinleri isteyerek başlayın.

sleep: yazabilmek için bildirmeniz gereken izin aşağıda verilmiştir:

<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 oturumu için izin isteme örneği gösterilmektedir:

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

Bunu yapmak için gerekli veri türleri için bir dizi izin 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(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)
)

Uygulamanıza gerekli izinlerin verilip verilmediğini görmek için getGrantedPermissions aracını kullanın. Aksi takdirde, bu izinleri istemek için createRequestPermissionResultContract seçeneğini 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 izinleri kullanmadan önce her seferinde kontrol etmeli ve izinlerin kaybedildiği senaryoları ele almalıdır.

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 uyku seansıyla eşleştirmek için oturumun startTime ile endTime arasındaki zaman damgalarıyla kaydedin. Health Connect, uyku oturumlarını ayrıntılı verilerle bağlamak için oturum tanımlayıcısı 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

Kalp atış hızı gibi ayrıntılı veriler uyku oturumu boyunca kaydedilebilir ancak SleepSessionRecord yalnızca oturum tamamlandıktan sonra (ör. kullanıcı uyandığında) Health Connect'e yazılmalıdır. 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 müşteri kaydı kimliği oluşturun.
2. Kullanıcı uyandığında veya uyku izleme durdurulduğunda tüm uyku aşamalarını toplayıp 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 verilerini okuma

Uygulamalar, aktiviteyi özetlemek, sağlık analizleri sağlamak 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 hakkında sorgu yapabilirsiniz.

İlişkili verilerle okuma oturumu

Kayıt türü olarak SleepSessionRecord ile birlikte ReadRecordsRequest kullanarak uyku oturumlarını okuyabilirsiniz. Bu oturumlar, zaman aralığına göre filtrelenir. Belirli bir uyku seansıyla ilişkili verileri okumak için seçilen veri türüyle ilgili ikinci bir istekte bulunun. Örneğin, uyku seansının HeartRateRecord, startTime ve endTime değerlerine göre filtreleme yapın.

Aşağıdaki örnekte, belirli bir zaman aralığı için ilişkili kalp atış hızı verileriyle uyku oturumları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önergelere uyun:

• Yazma Sıklığı
  • Etkin Uyku İzleme(Ön Plan): Etkin uyku izleme için verileri kullanılabilir hale geldikçe veya en fazla 15 dakikalık aralıklarla yazın.
  • Arka plan senkronizasyonu: Ertelenmiş yazma işlemleri için WorkManager kullanın. Gerçek zamanlı veriler ve pil verimliliği arasında denge kurmak için 15 dakikalık bir aralık hedefleyin.
  • Toplu işleme: Her bir 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 uyku seansı düzenlenir veya güncellenirse aynı kimliğin kullanılması, oturumun yeni ve ayrı bir uyku seansı olarak değerlendirilmesini engeller.
• Veri türleri için gruplandırma kullanın: Giriş/çıkış ek yükünü azaltmak ve pil ömrünü korumak için veri noktalarınızı tek bir insertRecords çağrısında gruplandırın. Her noktayı ayrı ayrı yazmayın.

• Yinelenen veriler yazmaktan kaçının: İstemci kimliklerini kullanın Kayıt oluştururken metadata.clientRecordId değerini 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, yinelenen kaydı yoksayar veya yeni bir kayıt oluşturmak yerine mevcut kaydı günceller. Senkronizasyon yeniden denemeleri veya uygulama yeniden yüklemeleri sırasında yinelenen öğeleri önlemenin en etkili yolu metadata.clientRecordId ayarlamaktır.

  val record = RespiratoryRateRecord(
      rate = 16.0,
      time = time,
      zoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "respiratory_rate_20231030_1"
      )
  )
  

• Mevcut verileri kontrol edin: 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, bir ö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 neden sağlık verilerine erişmesi gerektiğini açıklamak için Permission.createIntent akışını kullanın. Örneğin, "Uyku düzenlerinizi analiz etmek için" gibi bir açıklama yapabilirsiniz.

• Uzun süren oturumları test edin: Toplu işleme aralığınızın ve sensör kullanımınızın cihazın pilini tüketmediğini doğrulamak için birkaç saat süren oturumlar sırasında pil tüketimini izleyin.

• Zaman damgalarını sensör hızlarıyla eşleştirin: Verilerin yüksek doğruluğunu korumak için kayıt zaman damgalarınızı sensörlerinizin gerçek sıklığıyla eşleştirin.

Test

Verilerin doğruluğunu ve yüksek kaliteli bir kullanıcı deneyimi sağlamak için aşağıdaki test stratejilerini uygulayın ve resmi En sık kullanılan test senaryoları dokümanına bakın.

Doğrulama araçları

• Health Connect Araç Kutusu: Kayıtları manuel olarak incelemek, test verilerini silmek ve veritabanında değişiklikleri simüle etmek için bu yardımcı uygulamayı kullanın. Bu, kayıtlarınızın doğru şekilde saklandığını doğrulamanın en iyi yoludur.
• FakeHealthConnectClient ile birim testi: Uygulamanızın, fiziksel bir cihaza ihtiyaç duymadan izin iptali veya API istisnaları gibi uç durumları 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 karşılaşılan hata ayıklama adımları