2026'dan itibaren Google Fit API'lerin desteğini sonlandıracağız. Google Fit'e geçiş hakkında daha fazla bilgi için Taşıma Rehberi'ne bakın.

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 seansı 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 oturumları, 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.

İlişkili veriler ise bağımsız olarak kaydedilen ancak bir oturumun zaman aralığına giren verileri ifade eder. Örneğin, bir kullanıcı uyku oturumu sırasında kalp atış hızını kaydederse kalp atış hızı verileri, ilişkili veriler olur. Oturum kaydının bir parçası olan alt tür verilerinin aksine, ilişkili veriler bağımsız kayıtlardan oluşur ve her birinin kendi UUID'si vardır.

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ılıp kullanılamadığını 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 seansına erişim aşağıdaki izinlerle korunur:

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

Uygulamanıza uyku seansı özelliği eklemek için öncelikle SleepSession veri türüyle ilgili izin isteğinde bulunun.

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

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

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

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

Kullanıcıdan izin isteyin

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

Desteklenen toplamalar

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

SLEEP_DURATION_TOTAL

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 seansından 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"
            ),
        )
    )
}

Alt tür verilerinin, çakışmayan ve sıralı zaman damgalarına sahip bir oturumda hizalanması gerekir. Ancak boşluklara izin verilir.
Alt tür verileri UUID içermez ancak ilişkili verilerde farklı UUID'ler bulunur.
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 seanslarını yazma

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

Tüm uyku süresini kapsayan genel oturum.
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 = Instant.parse("2022-05-10T23:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T01:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_SLEEPING,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T01:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T02:30:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_LIGHT,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T02:30:00.000Z"),
        endTime = Instant.parse("2022-05-11T05:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_DEEP,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T05:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_REM,
    ),
)

SleepSessionRecord(
        title = "weekend sleep",
        startTime = Instant.parse("2022-05-10T23:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
        startZoneOffset = ZoneOffset.of("-08:00"),
        endZoneOffset = ZoneOffset.of("-08:00"),
        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 seansını 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)
}