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

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

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

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

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

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

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

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

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

איך בודקים אם אפליקציית 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
}

בהתאם לסטטוס שמוחזר על ידי 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.

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

אפשר להשתמש ב-getGrantedPermissions כדי לבדוק אם האפליקציה כבר קיבלה את ההרשאות הנדרשות. אם לא, משתמשים ב-createRequestPermissionResultContract כדי לבקש את ההרשאות האלה. הפעולה הזו תציג את מסך ההרשאות של 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)
  }
}

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

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

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

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

ריכזנו כאן כמה הנחיות לשימוש בנתוני שינה ב-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"
            ),
        )
    )
}
  • הנתונים של סוג המשנה צריכים להיות מיושרים בסשן עם חותמות זמן עוקבות שלא חופפות. אפשר להשתמש ברווחים.
  • נתוני סוג המשנה לא מכילים 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,
)

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

val stages = listOf(
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-10T23:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T01:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_SLEEPING,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T01:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T02:30:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_LIGHT,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T02:30:00.000Z"),
        endTime = Instant.parse("2022-05-11T05:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_DEEP,
    ),
    SleepSessionRecord.Stage(
        startTime = Instant.parse("2022-05-11T05:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
        stage = SleepSessionRecord.STAGE_TYPE_REM,
    ),
)

SleepSessionRecord(
        title = "weekend sleep",
        startTime = Instant.parse("2022-05-10T23:00:00.000Z"),
        endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
        startZoneOffset = ZoneOffset.of("-08:00"),
        endZoneOffset = ZoneOffset.of("-08:00"),
        stages = stages,
)

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

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

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

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

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

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