מעקב אחר נתוני שינה

המדריך הזה תואם לגרסה 1.1.0‎-alpha11 של Health Connect.

אפליקציית Health Connect מספקת סוג נתונים של סשן שינה, כדי לאחסן מידע על השינה של המשתמש, כמו סשן לילי או תנומה במהלך היום. סוג הנתונים SleepSessionRecord משמש לייצוג של הסשנים האלה.

הסשנים מאפשרים למשתמשים למדוד ביצועים לפי זמן לאורך תקופה מסוימת, כמו נתונים רציפים של קצב לב או מיקום.

סשנים של SleepSessionRecord מכילים נתונים שמתעדים את שלבי השינה, כמו AWAKE, SLEEPING ו-DEEP.

נתוני סוג משנה הם נתונים ש"שייכים" לסשן, והם רלוונטיים רק כשקוראים אותם עם סשן אב. לדוגמה, שלב שינה.

לעומת זאת, נתונים משויכים הם נתונים שנרשמים באופן עצמאי אבל נכללים בטווח הזמן של סשן. לדוגמה, אם משתמש מתעד את הדופק במהלך רשומת השינה שלו, נתוני הדופק הם נתונים משויכים. בניגוד לנתוני סוג משנה שהם חלק מרשומת הסשן, נתונים משויכים מורכבים מרשומות עצמאיות, שלכל אחת מהן יש UUID משלה.

בדיקת הזמינות של Health Connect

לפני שמנסים להשתמש ב-Health Connect, האפליקציה צריכה לוודא שהשירות זמין במכשיר של המשתמש. יכול להיות שאפליקציית Health Connect לא מותקנת מראש בחלק מהמכשירים או שהיא מושבתת. אפשר לבדוק את הזמינות באמצעות ה-method‏ HealthConnectClient.getSdkStatus().

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(), תוכלו להנחות את המשתמש להתקין או לעדכן את Health Connect מחנות Google Play, אם יש צורך בכך.

זמינות התכונה

אין דגל זמינות תכונות לסוג הנתונים הזה.

ההרשאות הנדרשות

הגישה לרשומת שינה מוגנת על ידי ההרשאות הבאות:

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

כדי להוסיף לאפליקציה אפשרות של רשומות שינה, צריך קודם לבקש הרשאות לסוג הנתונים SleepSession.

זו ההרשאה שצריך להצהיר עליה כדי שיהיה אפשר לכתוב נתוני שינה:

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

כדי לקרוא את נתוני סשן השינה, צריך לבקש את ההרשאות הבאות:

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

בקשת הרשאות מהמשתמש

אחרי שיוצרים מופע של לקוח, האפליקציה צריכה לבקש הרשאות מהמשתמש. צריך לאפשר למשתמשים להעניק או לדחות הרשאות בכל שלב. כדי לעשות זאת, יוצרים קבוצת הרשאות לסוגי הנתונים הנדרשים. קודם צריך לוודא שההרשאות בקבוצה מוצהרות במניפסט של Android.

val permissions =
    setOf(
        HealthPermission.getReadPermission(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class)
    )
HealthConnectManager.kt

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.") }
    }
}
HealthConnectActivity.kt

צבירות נתמכות

הערכים המצטברים הבאים זמינים עבור SleepSessionRecord:

• SLEEP_DURATION_TOTAL

הנחיות כלליות

ריכזנו כאן כמה הנחיות לשימוש בנתוני שינה ב-Health Connect.

• צריך להשתמש בסשנים כדי להוסיף נתונים מסשן שינה ספציפי, לשינה:

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

• נתוני סוג משנה צריכים להיות מיושרים בסשן עם חותמות זמן רציפות שלא חופפות. עם זאת, מותרים פערים.
• נתוני סוג המשנה לא מכילים UUID, אבל לנתונים המשויכים יש UUID שונים.
• הסשנים שימושיים אם המשתמש רוצה שהנתונים ישויכו לסשן (ויתועדו כחלק ממנו), ולא יתועדו באופן רציף.

מצב שינה

אתם יכולים לקרוא או לכתוב נתוני שינה ב-Health Connect. נתוני השינה מוצגים כסשן, ואפשר לחלק אותם ל-8 שלבי שינה שונים:

• ‫UNKNOWN: לא צוין או לא ידוע אם המשתמש ישן.
• ‫AWAKE: המשתמש ער במהלך מחזור שינה, לא במהלך היום.
• ‫SLEEPING: תיאור שינה כללי או לא מפורט.
• ‫OUT_OF_BED: המשתמש קם מהמיטה באמצע סשן שינה.
• ‫AWAKE_IN_BED: המשתמש ער במיטה.
• ‫LIGHT: המשתמש נמצא במחזור שינה קל.
• ‫DEEP: המשתמש נמצא במחזור שינה עמוקה.
• ‫REM: המשתמש נמצא במחזור שנת REM.

הערכים האלה מייצגים את סוג השינה שהמשתמש חווה בטווח זמן מסוים. לא חובה לכתוב את שלבי השינה, אבל מומלץ לעשות את זה אם הנתונים זמינים.

כתיבת נתוני השינה

סוג הנתונים SleepSessionRecord כולל שני חלקים:

1. הסשן הכולל, שמתפרס על כל משך השינה.
2. שלבים ספציפיים במהלך רשומת השינה, כמו שינה קלה או שינה עמוקה.

כך מוסיפים רשומת שינה בלי שלבים:

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

כך מוסיפים שלבים שמכסים את כל התקופה של רשומת שינה:

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

קריאת נתוני השינה

לכל רשומת שינה שמוחזרת, צריך לבדוק אם יש גם נתונים של שלבי השינה:

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
}
HealthConnectManager.kt

מחיקת רשומת שינה

כך מוחקים רשומת שינה. בדוגמה הזו השתמשנו ברשומת שינה:

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