A partire dal 2026, eseguiremo la transizione dalle API Google Fit. Per ulteriori informazioni sulla migrazione di Google Fit, consulta la guida alla migrazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Monitorare le sessioni di sonno

Questa guida è compatibile con la versione 1.1.0-alpha11 di Connessione Salute.

Connessione Salute fornisce un tipo di dati sessione di sonno per memorizzare informazioni sul sonno di un utente, ad esempio una sessione notturna o un pisolino diurno. Per rappresentare queste sessioni viene utilizzato il tipo di dati SleepSessionRecord.

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

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

I dati Tipo secondario sono dati "appartenenti" a una sessione e sono significativi solo se vengono letti con una sessione principale. Ad esempio, la fase del sonno.

Controllare la disponibilità di Connessione Salute

Prima di tentare di utilizzare Connessione Salute, la tua app deve verificare che Connessione Salute sia disponibile sul dispositivo dell'utente. Connessione Salute potrebbe non essere preinstallata su tutti i dispositivi o potrebbe essere disattivata. Puoi verificare la disponibilità utilizzando il metodo HealthConnectClient.getSdkStatus().

Come verificare la disponibilità di Connessione Salute

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 a installare o aggiornare 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 richieste

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 di scrittura 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, la tua app deve richiedere le autorizzazioni all'utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento.

A questo scopo, crea un insieme di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nell'insieme siano dichiarate prima nel file 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 alla tua app sono già state concesse le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Connessione Salute.

// 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 periodicamente le autorizzazioni concesse e gestire gli scenari in cui l'autorizzazione viene revocata.

Aggregazioni supportate

Per SleepSessionRecord sono disponibili i seguenti valori aggregati:

SLEEP_DURATION_TOTAL

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

Le sessioni non devono essere utilizzate per misurazioni generali, come il conteggio dei passi giornalieri.
I dati del sottotipo non contengono un UID, ma i dati associati hanno UID distinti.
I dati del sottotipo devono essere allineati in una sessione con timestamp sequenziali che non si sovrappongono. Tuttavia, sono consentiti spazi vuoti.
Le sessioni sono utili se l'utente vuole che i dati siano associati a una sessione (e monitorati come parte di questa), anziché registrati in modo continuo.

Sessioni di sonno

Puoi leggere o scrivere dati sul sonno in Connessione Salute. I dati sul sonno vengono visualizzati come 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 del sonno generica o non granulare.
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 si trova in un ciclo di sonno leggero.
DEEP: l'utente si trova in un ciclo di sonno profondo.
REM: l'utente si trova in un ciclo di 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.

Scrittura delle sessioni di sonno

Il tipo di dati SleepSessionRecord è composto da due parti:

La sessione complessiva, che copre l'intera durata del sonno.
Singole fasi durante la sessione di sonno, come il sonno leggero o 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 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,
)

Lettura di una sessione di sonno

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

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

Eliminare una sessione di sonno

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

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