Monitorare le sessioni di sonno

Questa guida è compatibile con la versione 1.1.0-alpha11 di Health Connect.

Health Connect fornisce un tipo di dati sessione di sonno per archiviare informazioni sul sonno di un utente, ad esempio una sessione notturna o un pisolino diurno. Il tipo di dati SleepSessionRecord viene utilizzato per rappresentare queste sessioni.

Le sessioni consentono agli utenti di misurare le prestazioni basate sul tempo in un determinato periodo, ad esempio i dati sulla frequenza cardiaca o sulla posizione continua.

Le sessioni SleepSessionRecord contengono dati che registrano le fasi del sonno, ad esempio AWAKE, SLEEPING e DEEP.

I dati sottotipo sono dati che "appartengono" a una sessione e sono significativi solo se vengono letti con una sessione principale. Ad esempio, la fase del sonno.

I dati associati, d'altra parte, si riferiscono ai dati registrati in modo indipendente, ma che rientrano nell'intervallo di tempo di una sessione. Ad esempio, se un utente registra la frequenza cardiaca durante la sessione di sonno, i dati sulla frequenza cardiaca saranno dati associati. A differenza dei dati sottotipo che fanno parte del record della sessione, i dati associati sono costituiti da record indipendenti, ognuno con il proprio UUID.

Controlla la disponibilità di Health Connect

Prima di tentare di utilizzare Health Connect, l'app deve verificare che Health Connect sia disponibile sul dispositivo dell'utente. Health Connect potrebbe non essere preinstallato su tutti i dispositivi o potrebbe essere disattivato. Puoi verificare la disponibilità utilizzando il metodo HealthConnectClient.getSdkStatus().

Come verificare la disponibilità di Health Connect

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
}

A seconda dello stato restituito da getSdkStatus(), puoi guidare l'utente all'installazione o all'aggiornamento di Connessione Salute dal Google Play Store, se necessario.

Disponibilità della funzionalità

Non esiste un flag di disponibilità delle funzionalità per questo tipo di dati.

Autorizzazioni obbligatorie

L'accesso alla sessione di sonno è protetto dalle seguenti autorizzazioni:

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

Per aggiungere la funzionalità di sessione di sonno alla tua app, inizia richiedendo le autorizzazioni per il tipo di dati SleepSession.

Ecco l'autorizzazione che devi dichiarare per poter scrivere la sessione di sonno:

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

Per leggere la sessione di sonno, devi richiedere le seguenti autorizzazioni:

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

Richiedi le autorizzazioni all'utente

Dopo aver creato un'istanza client, l'app deve richiedere le autorizzazioni all'utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento.

A questo scopo, crea un set di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nel set siano dichiarate prima nel manifest di Android.

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

Utilizza getGrantedPermissions per verificare se la tua app ha già le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Health Connect.

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

Poiché gli utenti possono concedere o revocare le autorizzazioni in qualsiasi momento, la tua app deve controllare le autorizzazioni ogni volta prima di utilizzarle e gestire gli scenari in cui l'autorizzazione viene revocata.

Aggregazioni supportate

I seguenti valori aggregati sono disponibili per SleepSessionRecord:

Indicazioni generali

Ecco alcune linee guida sulle best practice per lavorare con le sessioni di sonno in Health Connect.

  • Le sessioni devono essere utilizzate per aggiungere dati da una sessione di sonno specifica, per il sonno:

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

  • I dati sottotipo devono essere allineati in una sessione con timestamp sequenziali che non si sovrappongono. Tuttavia, sono consentiti intervalli.
  • I dati sottotipo non contengono un UUID, ma i dati associati hanno UUID distinti.
  • Le sessioni sono utili se l'utente vuole che i dati siano associati a una sessione (e monitorati come parte di essa), anziché registrati in modo continuo.

Sessioni di sonno

Puoi leggere o scrivere dati relativi al sonno in Health Connect. I dati relativi al sonno vengono visualizzati come una sessione e possono essere suddivisi in 8 fasi del sonno distinte:

  • UNKNOWN: non specificato o sconosciuto se l'utente sta dormendo.
  • AWAKE: l'utente è sveglio durante un ciclo del sonno, non durante il giorno.
  • SLEEPING: descrizione generica o non granulare del sonno.
  • OUT_OF_BED: l'utente si alza dal letto nel bel mezzo di una sessione di sonno.
  • AWAKE_IN_BED: l'utente è sveglio a letto.
  • LIGHT: l'utente è in un ciclo del sonno leggero.
  • DEEP: l'utente è in un ciclo del sonno profondo.
  • REM: l'utente è in un ciclo del sonno REM.

Questi valori rappresentano il tipo di sonno che un utente sperimenta in un intervallo di tempo. La scrittura delle fasi del sonno è facoltativa, ma consigliata se disponibile.

Scrivi sessioni di sonno

Il tipo di dati SleepSessionRecord è composto da due parti:

  1. La sessione complessiva, che copre l'intera durata del sonno.
  2. Le singole fasi durante la sessione di sonno, come il sonno leggero o il sonno profondo.

Ecco come inserire una sessione di sonno senza fasi:

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

Ecco come aggiungere le fasi che coprono l'intero periodo di una sessione di sonno:

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

Leggi una sessione di sonno

Per ogni sessione di sonno restituita, devi verificare se sono presenti anche i dati sulle fasi del sonno:

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
}

Elimina una sessione di sonno

Ecco come eliminare una sessione. Per questo esempio, abbiamo utilizzato una sessione di sonno:

val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)