פיתוח חוויות שינה באמצעות Health Connect

אם אתם רוצים ליצור באפליקציה שלכם חוויה של מעקב אחר השינה, אתם יכולים להשתמש ב-Health Connect כדי לבצע פעולות כמו:

• כתיבת נתוני השינה
• כתיבה של נתוני שלב השינה
• כתיבה של נתוני שינה כמו דופק, רמת החמצן בדם וקצב הנשימה
• קריאת נתוני שינה מאפליקציות אחרות

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

סקירה כללית: יצירת כלי מקיף למעקב אחרי השינה

כדי ליצור חוויית מעקב אחר השינה מקיפה באמצעות Health Connect, אפשר לבצע את השלבים העיקריים הבאים:

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

תהליך העבודה הזה מאפשר אינטראופרביליות עם אפליקציות אחרות של Health Connect ומאמת את הגישה לנתונים שנשלטת על ידי המשתמש.

לפני שמתחילים

לפני שמטמיעים תכונות שינה:

• משלבים את Health Connect באמצעות התלות המתאימה.
• יוצרים מכונת HealthConnectClient.
• מוודאים שהאפליקציה מטמיעה תהליכי הרשאה בזמן ריצה שמבוססים על Health Permissions.

מושגים מרכזיים

נתוני השינה ב-Health Connect מיוצגים באמצעות כמה רכיבי ליבה. SleepSessionRecord משמש כרשומה מרכזית של נתוני השינה, ומכיל פרטים כמו שעת ההתחלה או הסיום ושלבי השינה. במהלך סשן, יכולים להירשם סוגים שונים של נתונים, כמו HeartRateRecord או OxygenSaturationRecord.

מצב שינה

נתוני השינה מיוצגים על ידי SleepSessionRecord. כל רשומה כוללת:

• startTime
• endTime
• ‫stages: רשימה של SleepSessionRecord.Stage כולל שינה עמוקה, שינה קלה, שנת REM ושינה במצב ערות.
• מטא-נתונים אופציונליים של הסשן (שם, הערות)

אפליקציות עשויות לכתוב כמה סוגי נתונים שמשויכים לסשן.

סוגי הנתונים

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

• ‫SleepSessionRecord: מתעד את משך השינה ואת השלבים שלה, כולל שינה עמוקה, שינה קלה, שנת REM וערות.
• ‫HeartRateRecord: תיעוד הדופק במהלך השינה.
• ‫OxygenSaturationRecord: רמת החמצן בדם (סטורציה) שנמדדת במהלך השינה.
• ‫RespiratoryRateRecord: מתעד את קצב הנשימה במהלך השינה.

כל סוג נתונים נשמר כרשומה נפרדת.

שיקולי פיתוח

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

ביצוע ברקע

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

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

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

הרשאות

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

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

• 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),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(OxygenSaturationRecord::class),
        HealthPermission.getWritePermission(OxygenSaturationRecord::class),
        HealthPermission.getReadPermission(RespiratoryRateRecord::class),
        HealthPermission.getWritePermission(RespiratoryRateRecord::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

הטמעה של רשומת שינה

בקטע הזה מתואר תהליך העבודה המומלץ לתיעוד נתוני שינה.

כדי להתאים סוגי נתונים כמו HeartRateRecord או OxygenSaturationRecord לרשומת שינה, צריך לתעד אותם עם חותמות זמן שחלות בין startTime לבין endTime של הרשומה. ‫Health Connect לא משתמש במזהה סשן כדי לקשר בין סשנים של שינה לבין נתונים מפורטים. במקום זאת, השיוך הוא מרומז באמצעות חפיפה בין מרווחי זמן. כשקוראים נתוני שינה, אפשר להשתמש בטווח הזמן של סשן כדי לשלוח שאילתה לגבי סוגי נתונים משויכים, כמו שמוסבר במאמר קריאת נתוני שינה.

כתיבת נתוני סשן

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

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

1. יוצרים מזהה ייחודי של רשומת לקוח.
2. כשהמשתמש מתעורר או כשמעקב אחר השינה מופסק, אוספים את כל שלבי השינה ויוצרים SleepSessionRecord.
3. מוסיפים את הרשומה באמצעות insertRecords.

דוגמה:

val clientRecordId = UUID.randomUUID().toString()
val sessionStartTime = LocalDateTime.of(2023, 10, 30, 22, 0).toInstant(ZoneOffset.UTC)
val sessionEndTime = LocalDateTime.of(2023, 10, 31, 7, 0).toInstant(ZoneOffset.UTC)

val stages = mutableListOf<SleepSessionRecord.Stage>()
// Add recorded stages, for example:
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(3600),
    endTime = sessionStartTime.plusSeconds(7200),
    stage = SleepSessionRecord.STAGE_TYPE_LIGHT)
)
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(7200),
    endTime = sessionStartTime.plusSeconds(10800),
    stage = SleepSessionRecord.STAGE_TYPE_DEEP)
)
// ... other stages

val session = SleepSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    stages = stages,
    metadata = Metadata(clientRecordId = clientRecordId)
)

healthConnectClient.insertRecords(listOf(session))

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

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

סשן קריאה עם נתונים משויכים

אפשר לקרוא סשנים של שינה באמצעות ReadRecordsRequest עם SleepSessionRecord כסוג הרשומה, מסונן לפי טווח זמן. כדי לקרוא נתונים משויכים של סשן נתון, שולחים בקשה שנייה לסוג הנתונים שנבחר, למשל HeartRateRecord – סינון לפי startTime ו-endTime של סשן השינה.

בדוגמה הבאה מוצגות שיטות לקריאת נתוני שינה עם נתוני דופק משויכים לטווח זמן נתון:

suspend fun readSleepSessionsWithAssociatedData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = SleepSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (sleepRecord in response.records) {
        // Process each session
        val stages = sleepRecord.stages
        val notes = sleepRecord.notes

        // To read specific granular data (like heart rate) that occurred during
        // this session, use the session's startTime and endTime to filter
        // the request for that data type.
        val hrResponse = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    sleepRecord.startTime,
                    sleepRecord.endTime
                )
            )
        )
        for (heartRateRecord in hrResponse.records) {
            for (sample in heartRateRecord.samples) {
                val bpm = sample.beatsPerMinute
            }
        }
    }
}

שיטות מומלצות

כדי לשפר את מהימנות הנתונים ואת חוויית המשתמש, כדאי לפעול לפי ההנחיות הבאות:

• כתיבה בתדירות גבוהה במהלך מעקב פעיל: כשמפעילים מעקב פעיל, כותבים את הנתונים כשהם זמינים או במרווח זמן מקסימלי של 15 דקות.
• שימוש ב-WorkManager לסנכרון ברקע: שימוש ב-WorkManager לכתיבות שנדחות. מומלץ להגדיר מרווח של 15 דקות כדי ליצור איזון בין נתונים בזמן אמת לבין יעילות הסוללה.
• בקשות לכתיבת נתונים בקבוצות: אל תכתבו כל אירוע של חיישן בנפרד. כדאי לחלק את הבקשות. Health Connect יכול לטפל בעד 1,000 רשומות לכל בקשת כתיבה.
• שמירה על מזהי סשנים קבועים וייחודיים: צריך להשתמש במזהים עקביים לסשנים. אם עורכים או מעדכנים סשן, שימוש באותו מזהה מונע מהמערכת להתייחס אליו כסשן חדש ונפרד.
• שימוש באצווה לסוגי נתונים: כדי לצמצם את התקורה של קלט/פלט ולשמור על חיי הסוללה, כדאי לקבץ את נקודות הנתונים לקריאה יחידה של insertRecords במקום לכתוב כל נקודה בנפרד.
• כדי למנוע כתיבה של נתונים כפולים: משתמשים במזהי לקוח: כשיוצרים רשומות, מגדירים metadata.clientRecordId. מערכת Health Connect משתמשת במזהה הזה כדי לזהות רשומות ייחודיות. אם מנסים לכתוב רשומה עם clientRecordId שכבר קיים, מערכת Health Connect מתעלמת מהכפילות או מעדכנת את הרשומה הקיימת במקום ליצור רשומה חדשה. הגדרת metadata.clientRecordId היא הדרך היעילה ביותר למנוע כפילויות במהלך ניסיונות חוזרים לסנכרון או התקנה מחדש של אפליקציה.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• בדיקת נתונים קיימים: לפני שמסנכרנים, שולחים שאילתה לטווח הזמן כדי לראות אם רשומות מהאפליקציה כבר קיימות.
• מוודאים שחותמות הזמן לא חופפות: חשוב לוודא שסשן חדש לא מתחיל לפני שהסשן הקודם מסתיים. חפיפה בין סשנים עלולה לגרום לקונפליקטים בלוחות הבקרה של הכושר ובחישובים של הסיכומים.
• לספק נימוקים ברורים להרשאה: צריך להשתמש בתהליך Permission.createIntent כדי להסביר למה האפליקציה צריכה גישה לנתונים בתחום הבריאות. לדוגמה: 'כדי לעקוב אחרי המגמות של לחץ הדם ולספק תובנות'.
• בדיקת סשנים ארוכים: מעקב אחרי צריכת הסוללה במהלך סשנים שנמשכים כמה שעות כדי לוודא שמרווח האצווה ושימוש בחיישן לא מרוקנים את הסוללה של המכשיר.
• התאמת חותמות הזמן לקצב החיישנים: כדי לשמור על רמת מהימנות גבוהה של הנתונים, צריך להתאים את חותמות הזמן של הרשומה לתדירות בפועל של החיישנים.

בדיקה

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

כלי אימות

• ארגז הכלים של Health Connect: אפשר להשתמש באפליקציה הנלווית הזו כדי לבדוק רשומות באופן ידני, למחוק נתוני בדיקה ולבצע סימולציה של שינויים במסד הנתונים. זו הדרך הכי טובה לוודא שהרשומות שלכם מאוחסנות בצורה נכונה.
• בדיקות יחידה באמצעות FakeHealthConnectClient: אפשר להשתמש בספריית הבדיקות כדי לוודא איך האפליקציה מטפלת במקרים קיצוניים, כמו ביטול הרשאה או חריגות ב-API, בלי צורך במכשיר פיזי.

רשימת משימות לבדיקת איכות

ארכיטקטורה אופיינית

הטמעה של מעקב אחר השינה כוללת בדרך כלל:

פתרון בעיות

שלבים נפוצים לניפוי באגים