Schlafeinheiten aufzeichnen

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha11 kompatibel.

Health Connect bietet den Datentyp Schlafeinheit zum Speichern von Informationen zum Schlaf eines Nutzers, z. B. eine nächtliche Schlafeinheit oder ein Nickerchen am Tag. Der Datentyp SleepSessionRecord wird verwendet, um diese Sitzungen darzustellen.

Mit Sitzungen können Nutzer die zeitbasierte Leistung über einen bestimmten Zeitraum hinweg messen, z. B. die kontinuierliche Herzfrequenz oder Standortdaten.

SleepSessionRecord-Sitzungen enthalten Daten zu Schlafphasen wie AWAKE, SLEEPING und DEEP.

Untertypdaten gehören zu einer Sitzung und sind nur sinnvoll, wenn sie mit einer übergeordneten Sitzung gelesen werden. Zum Beispiel die Schlafphase.

Zugehörige Daten sind Daten, die unabhängig aufgezeichnet werden, aber in den Zeitraum einer Sitzung fallen. Wenn ein Nutzer beispielsweise während seiner Schlafeinheit die Herzfrequenz aufzeichnet, sind die Herzfrequenzdaten zugehörige Daten. Im Gegensatz zu Untertypdaten, die Teil des Sitzungsdatensatzes sind, bestehen zugehörige Daten aus unabhängigen Datensätzen mit jeweils eigener UUID.

Verfügbarkeit von Health Connect prüfen

Bevor Sie versuchen, Health Connect zu verwenden, sollte Ihre App prüfen, ob Health Connect auf dem Gerät des Nutzers verfügbar ist. Health Connect ist möglicherweise nicht auf allen Geräten vorinstalliert oder wurde deaktiviert. Sie können die Verfügbarkeit mit der Methode HealthConnectClient.getSdkStatus() prüfen.

Verfügbarkeit von Health Connect prüfen

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
}

Je nach dem von getSdkStatus() zurückgegebenen Status kannst du den Nutzer bei Bedarf anleiten, Health Connect aus dem Google Play Store zu installieren oder zu aktualisieren.

Verfügbarkeit der Funktion

Für diesen Datentyp ist kein Verfügbarkeitskennzeichen für Funktionen vorhanden.

Erforderliche Berechtigungen

Der Zugriff auf Schlafeinheiten wird durch die folgenden Berechtigungen geschützt:

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

Wenn Sie Ihrer App die Funktion zum Aufzeichnen von Schlafeinheiten hinzufügen möchten, müssen Sie zuerst Berechtigungen für den Datentyp SleepSession anfordern.

Hier ist die Berechtigung, die Sie deklarieren müssen, um Schlafeinheiten schreiben zu können:

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

Zum Lesen von Schlafeinheiten müssen Sie die folgenden Berechtigungen anfordern:

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

Berechtigungen vom Nutzer anfordern

Nachdem Sie eine Client-Instanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen jederzeit die Möglichkeit haben, Berechtigungen zu erteilen oder zu verweigern. Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Die Berechtigungen im Set müssen zuerst in Ihrem Android-Manifest deklariert werden. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class)
    )
 Verwenden Sie getGrantedPermissions, um zu prüfen, ob Ihrer App bereits die erforderlichen Berechtigungen erteilt wurden. Falls nicht, verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Dadurch wird der Health Connect-Berechtigungsbildschirm angezeigt. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss Ihre App jedes Mal, bevor sie Berechtigungen verwendet, prüfen, ob sie vorhanden sind, und Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

Unterstützte Aggregationen

Für SleepSessionRecord sind die folgenden aggregierten Werte verfügbar:

Allgemeine Anleitung

Hier sind einige Best Practices für die Arbeit mit Schlafeinheiten in Health Connect.

  • Sitzungen sollten verwendet werden, um Daten aus einer bestimmten Schlafeinheit hinzuzufügen, für den Schlaf:

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

  • Untertypdaten müssen in einer Sitzung mit sequenziellen Zeitstempeln ausgerichtet werden, die sich nicht überschneiden. Lücken sind jedoch zulässig.
  • Untertypdaten enthalten keine UUID, aber zugeordnete Daten haben eindeutige UUIDs.
  • Sitzungen sind nützlich, wenn Nutzer möchten, dass Daten einer Sitzung zugeordnet und als Teil einer Sitzung erfasst werden, anstatt kontinuierlich aufgezeichnet zu werden.

Schlafeinheiten

Sie können Schlafdaten in Health Connect lesen oder schreiben. Schlafdaten werden als Sitzung angezeigt und können in acht verschiedene Schlafphasen unterteilt werden:

  • UNKNOWN: Nicht angegeben oder unbekannt, wenn der Nutzer schläft.
  • AWAKE: Der Nutzer ist innerhalb eines Schlafzyklus wach, nicht tagsüber.
  • SLEEPING: Allgemeine oder nicht detaillierte Schlafbeschreibung.
  • OUT_OF_BED: Der Nutzer steht mitten in einer Schlafeinheit auf.
  • AWAKE_IN_BED: Der Nutzer ist wach im Bett.
  • LIGHT: Der Nutzer befindet sich in einer Phase des leichten Schlafs.
  • DEEP: Der Nutzer befindet sich in einem Tiefschlafzyklus.
  • REM: Der Nutzer befindet sich in einem REM-Schlafzyklus.

Diese Werte geben den Schlaftyp an, den ein Nutzer in einem bestimmten Zeitraum hat. Das Schreiben von Schlafphasen ist optional, wird aber empfohlen, sofern verfügbar.

Schlafdauer schreiben

Der Datentyp SleepSessionRecord hat zwei Teile:

  1. Die gesamte Sitzung, die die gesamte Schlafdauer umfasst.
  2. Einzelne Phasen während der Schlafeinheit, z. B. Leicht- oder Tiefschlaf.

So fügst du eine Schlafeinheit ohne Phasen ein:

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

So fügst du Phasen hinzu, die den gesamten Zeitraum einer Schlafeinheit abdecken:

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

Schlafeinheit lesen

Prüfe für jeden zurückgegebenen Schlafeintrag, ob auch Daten zu Schlafphasen vorhanden sind:

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
}

Schlafeintrag löschen

So löschst du eine Einheit. In diesem Beispiel haben wir eine Schlafeinheit verwendet:

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