A partir de 2026, vamos migrar das APIs do Google Fit. Para mais informações sobre a migração do Google Fit, consulte o guia de migração.

Esta página foi traduzida pela API Cloud Translation.

Monitorar sessões de sono

Este guia é compatível com a versão 1.1.0-alpha11 do Health Connect.

O Conexão Saúde oferece um tipo de dados de sessão de sono para armazenar informações sobre o sono de um usuário, como uma sessão noturna ou uma soneca diurna. O tipo de dados SleepSessionRecord é usado para representar essas sessões.

As sessões permitem que os usuários meçam a performance com base no tempo durante um período, como frequência cardíaca contínua ou dados de local.

As sessões SleepSessionRecord contêm dados que registram os estágios do sono, como AWAKE, SLEEPING e DEEP.

Os dados de subtipo são aqueles que "pertencem" a uma sessão e que só são significativos quando lidos com uma sessão mãe. Por exemplo, estágio do sono.

Verificar a disponibilidade da Conexão Saúde

Antes de tentar usar o Conexão Saúde, seu app precisa verificar se ele está disponível no dispositivo do usuário. A Conexão Saúde pode não estar pré-instalada em todos os dispositivos ou pode estar desativada. É possível verificar a disponibilidade usando o método HealthConnectClient.getSdkStatus().

Como verificar a disponibilidade da Conexão Saúde

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
}

Dependendo do status retornado por getSdkStatus(), você pode orientar o usuário a instalar ou atualizar o Conexão Saúde na Google Play Store, se necessário.

Disponibilidade do recurso

Não há uma flag de disponibilidade de recurso para esse tipo de dado.

Permissões necessárias

O acesso à sessão de sono é protegido pelas seguintes permissões:

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

Para adicionar a capability de sessão de sono ao app, comece solicitando permissões de gravação do tipo de dado SleepSession.

Confira a permissão necessária para poder gravar uma sessão de sono:

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

Para ler a sessão de sono, solicite as seguintes permissões:

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

Solicitar permissões do usuário

Depois de criar uma instância de cliente, seu app precisa solicitar permissões do usuário. Os usuários precisam poder conceder ou negar permissões a qualquer momento.

Para isso, crie um conjunto de permissões para os tipos de dados necessários. Verifique se as permissões no conjunto foram declaradas primeiro no manifesto do Android.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(SleepSessionRecord::class),
  HealthPermission.getWritePermission(SleepSessionRecord::class)
)

Use getGrantedPermissions para verificar se o app já tem as permissões necessárias concedidas. Caso contrário, use createRequestPermissionResultContract para solicitar essas permissões. Isso mostra a tela de permissões da Conexão Saúde.

// 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)
  }
}

Como os usuários podem conceder ou revogar permissões a qualquer momento, seu app precisa verificar periodicamente as permissões concedidas e lidar com cenários em que a permissão é perdida.

Agregações compatíveis

Estes são os valores agregados disponíveis para SleepSessionRecord:

SLEEP_DURATION_TOTAL

Diretrizes gerais

Confira algumas práticas recomendadas para trabalhar com sessões de sono na Conexão Saúde.

Use as sessões para adicionar dados de uma sessão de sono específica de sono:

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

As sessões não são usadas para medições gerais, como contagens diárias de passos.
Os dados de subtipo não contêm um UID, mas os dados associados têm UIDs distintos.
Os dados de subtipo precisam estar alinhados em uma sessão com carimbos de data/hora sequenciais que não se sobrepõem. No entanto, lacunas são permitidas.
As sessões são úteis quando o usuário quer que os dados sejam associados e monitorados como parte de uma sessão, em vez de registrados continuamente.

Sessões de sono

Você pode ler ou gravar dados de sono na Conexão Saúde. Os dados de sono são mostrados como uma sessão e podem ser divididos em oito estágios distintos de sono:

UNKNOWN: não especificado ou desconhecido se o usuário estiver dormindo.
AWAKE: o usuário está acordado durante o período de um ciclo de sono. Não é registrado durante o dia.
SLEEPING: descrição de sono genérica ou não granular.
OUT_OF_BED: o usuário sai da cama no meio de uma sessão de sono.
AWAKE_IN_BED: o usuário está acordado na cama.
LIGHT: o usuário está em um ciclo de sono leve.
DEEP: o usuário está em um ciclo de sono profundo.
REM: o usuário está em um ciclo de sono REM.

Esses valores representam o tipo de sono de um usuário dentro de um período. Gravar os estágios do sono é opcional. Recomendamos salvar, se possível.

Gravar sessões de sono

O tipo de dados SleepSessionRecord têm duas partes:

A sessão geral, que abrange toda a duração do sono.
Estágios individuais durante a sessão de sono, como sono leve ou profundo.

Confira como inserir uma sessão de sono sem estágios:

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

Confira como adicionar estágios que abrangem todo o período de uma sessão de sono:

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,
)

Ler uma sessão de sono

Para cada sessão de sono retornada, verifique se os dados do estágio de sono também estão presentes:

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
    }
}

Excluir uma sessão de sono

Saiba como excluir uma sessão. Neste exemplo, usamos uma sessão de sono:

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