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

המדריך הזה תואם לגרסה 1.1.0‎-alpha12 של 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"
    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",
                metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH))
            ),
        )
    )
}
HealthConnectManager.kt

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

רשומות שינה

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

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

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

כתיבה של נתוני רשומות השינה

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

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

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

val zoneRules = ZoneId.systemDefault().rules

// Calculate the specific offset for both start and end times
val startOffset = zoneRules.getOffset(startTime)
val endOffset = zoneRules.getOffset(endTime)

SleepSessionRecord(
    title = "weekend sleep",
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = startOffset,
    endZoneOffset = endOffset,
    metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH))
)
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