Uyku oturumlarını izleme

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

Health Connect, kullanıcının uykusuyla ilgili bilgileri (ör. gece uykusu veya gündüz uykusu) depolamak için uyku oturumu veri türünü sağlar. Bu oturumları temsil etmek için SleepSessionRecord veri türü kullanılır.

Oturumlar, kullanıcıların belirli bir süre boyunca zamana dayalı performansı (ör. sürekli kalp atış hızı veya konum verileri) ölçmesine olanak tanır.

SleepSessionRecord seansları, AWAKE, SLEEPING ve DEEP gibi uyku aşamalarını kaydeden verileri içerir.

Alt tür verileri, bir oturuma "ait" olan ve yalnızca bir üst oturumla birlikte okunduğunda anlamlı olan verilerdir. Örneğin, uyku evresi.

Health Connect'in kullanılabilirliğini kontrol etme

Uygulamanız, Health Connect'i kullanmaya çalışmadan önce kullanıcının cihazında Health Connect'in kullanılabilir olduğunu doğrulamalıdır. Health Connect bazı cihazlarda önceden yüklenmemiş veya devre dışı bırakılmış olabilir. HealthConnectClient.getSdkStatus() yöntemini kullanarak kullanılabilirliği kontrol edebilirsiniz.

Health Connect'in kullanılabilirliğini kontrol etme

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

getSdkStatus() tarafından döndürülen duruma bağlı olarak, gerekirse kullanıcıyı Google Play Store'dan Health Connect'i yüklemeye veya güncellemeye yönlendirebilirsiniz.

Özellik kullanılabilirliği

Bu veri türü için özellik kullanılabilirliği işareti yoktur.

Gerekli izinler

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

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

Uygulamanıza uyku oturumu özelliği eklemek için öncelikle SleepSession veri türü için yazma izni isteyerek başlayın.

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

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

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

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

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.

Bunu yapmak için gerekli veri türleri için bir dizi izin oluşturun. Gruptaki izinlerin önce Android manifestinizde beyan edildiğinden emin olun.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(SleepSessionRecord::class),
  HealthPermission.getWritePermission(SleepSessionRecord::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ı ele alması gerekir.

Desteklenen toplamalar

SleepSessionRecord için aşağıdaki toplu değerler kullanılabilir:

Genel kurallar

Health Connect'te uyku oturumlarıyla çalışma hakkında bazı en iyi uygulama yönergelerini aşağıda bulabilirsiniz.

  • Oturumlar, belirli bir uyku oturumundan veri eklemek için kullanılmalıdır: uyku için:
suspend fun writeSleepSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            SleepSessionRecord(
                startTime = Instant.parse("2022-05-10T23:00:00.000Z"),
                startZoneOffset = ZoneOffset.of("-08:00"),
                endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
                endZoneOffset = ZoneOffset.of("-08:00"),
                title = "My Sleep"
            ),
        )
    )
}
  • Oturumlar, günlük adım sayısı gibi genel ölçümler için kullanılmamalıdır.
  • Alt tür verileri UID içermez ancak ilişkili verilerde farklı UID'ler bulunur.
  • Alt tür verilerinin, çakışmayan sıralı zaman damgalarıyla bir oturumda hizalanması gerekir. Ancak boşluklara izin verilir.
  • Kullanıcı, verilerin sürekli olarak kaydedilmesi yerine bir oturumla ilişkilendirilmesini (ve oturumun bir parçası olarak izlenmesini) istiyorsa oturumlar kullanışlıdır.

Uyku seansları

Health Connect'te uyku verilerini okuyabilir veya yazabilirsiniz. Uyku verileri oturum olarak gösterilir ve 8 farklı uyku aşamasına ayrılabilir:

  • UNKNOWN: Kullanıcının uyuyup uyumadığı belirtilmemiş veya bilinmiyor.
  • AWAKE: Kullanıcı, gündüz değil uyku döngüsü içinde uyanıktır.
  • SLEEPING: Genel veya ayrıntılı olmayan uyku açıklaması.
  • OUT_OF_BED: Kullanıcı, uyku seansının ortasında yataktan kalkar.
  • AWAKE_IN_BED: Kullanıcı yatakta uyanıktır.
  • LIGHT: Kullanıcı hafif uyku döngüsündedir.
  • DEEP: Kullanıcı derin uyku döngüsündedir.
  • REM: Kullanıcı REM uykusu döngüsündedir.

Bu değerler, kullanıcının belirli bir zaman aralığında yaşadığı uyku türünü gösterir. Uyku aşamalarını yazmak isteğe bağlıdır ancak mümkünse önerilir.

Uyku oturumlarını yazma

SleepSessionRecord veri türü iki bölümden oluşur:

  1. Tüm uyku süresini kapsayan genel oturum.
  2. Uyku oturumu sırasındaki aşamalar (ör. hafif uyku veya derin uyku).

Aşamalar olmadan uyku seansı eklemek için:

SleepSessionRecord(
      title = "weekend sleep",
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
)

Uyku seansının tamamını kapsayan aşamaları eklemek için:

val stages = listOf(
    SleepSessionRecord.Stage(
        startTime = START_TIME
        endTime = END_TIME,
        stage = SleepSessionRecord.STAGE_TYPE_SLEEPING,
    )
)

SleepSessionRecord(
        title = "weekend sleep",
        startTime = START_TIME,
        endTime = END_TIME,
        startZoneOffset = START_ZONE_OFFSET,
        endZoneOffset = END_ZONE_OFFSET,
        stages = stages,
)

Uyku seansını okuma

Döndürülen her uyku oturumu için uyku aşaması verilerinin de mevcut olup olmadığını kontrol etmeniz gerekir:

suspend fun readSleepSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                SleepSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (sleepRecord in response.records) {
        // Retrieve relevant sleep stages from each sleep record
        val sleepStages = sleepRecord.stages
    }
}

Uyku oturumunu silme

Oturumları silmek için aşağıdaki adımları uygulayın. Bu örnekte, uyku oturumu kullandık:

suspend fun deleteSleepSession(
    healthConnectClient: HealthConnectClient,
    sleepRecord: SleepSessionRecord,
) {
    val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
    healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)
}