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

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

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

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

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

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

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

• בקשת ההרשאות המתאימות לסוגי נתונים של מדדים חיוניים.
• כתיבת נתונים של מדדים חיוניים באמצעות רשומות כמו BloodPressureRecord,‏ HeartRateRecord ורשומות אחרות של מדדים חיוניים.
• קריאת נתונים של סימנים חיוניים לצורך הצגה, ניתוח או סנכרון.
• שימוש באצווה לכתיבה ולקריאה יעילות של נתונים.

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

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

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

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

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

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

סוגי נתונים של מדדים חיוניים

נתוני המדדים החיוניים מיוצגים על ידי סוגי רשומות נפרדים. סוגים נפוצים:

• ‫BloodPressureRecord: מייצג מדידה אחת של לחץ דם, כולל לחץ סיסטולי ודיאסטולי ותנוחת הגוף.
• ‫HeartRateRecord: מייצג סדרה של מדידות דופק.
• ‫RestingHeartRateRecord: מייצג מדידה אחת של דופק במנוחה.
• ‫BodyTemperatureRecord: מייצג קריאה אחת של טמפרטורת הגוף, כולל מיקום המדידה.
• ‫BloodGlucoseRecord: מייצג מדידה אחת של רמת הסוכר בדם, כולל הקשר לארוחה ולמקור הדגימה.
• ‫OxygenSaturationRecord: מייצג קריאה אחת של רמת החמצן בדם.
• ‫RespiratoryRateRecord: מייצג מדידה אחת של קצב הנשימה.

לרשימה המלאה של סוגי הנתונים, עיינו במאמר סוגי הנתונים ב-Health Connect.

שיקולי פיתוח

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

הרשאות

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

• לחץ דם: הרשאות קריאה וכתיבה של BloodPressureRecord.
• דופק: הרשאות קריאה וכתיבה של HeartRateRecord.
• דופק במנוחה: הרשאות קריאה וכתיבה של RestingHeartRateRecord.
• טמפרטורת הגוף: הרשאות קריאה וכתיבה של BodyTemperatureRecord.
• רמת סוכר בדם: הרשאות קריאה וכתיבה של BloodGlucoseRecord.
• רמת החמצן בדם: הרשאות קריאה וכתיבה של OxygenSaturationRecord.
• קצב הנשימה: הרשאות קריאה וכתיבה של RespiratoryRateRecord.

כך מבקשים הרשאות ללחץ דם, דופק וטמפרטורת הגוף:

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(BloodPressureRecord::class),
        HealthPermission.getWritePermission(BloodPressureRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(BodyTemperatureRecord::class),
        HealthPermission.getWritePermission(BodyTemperatureRecord::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

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

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

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

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

• android.permission.health.READ_BLOOD_PRESSURE
• android.permission.health.WRITE_BLOOD_PRESSURE

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

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

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

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

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

כתיבת נתונים של מדדים חיוניים

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

דוגמה לכתיבת BloodPressureRecord:

suspend fun writeBloodPressureRecord(healthConnectClient: HealthConnectClient) {
    val record = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    healthConnectClient.insertRecords(listOf(record))
}

כתיבה באצווה

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

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

suspend fun writeBatchRecords(healthConnectClient: HealthConnectClient) {
    val bloodPressureRecord = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    val heartRateRecord = HeartRateRecord(
        startTime = Instant.now().minusSeconds(60),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        samples = listOf(HeartRateRecord.Sample(time = Instant.now().minusSeconds(30), beatsPerMinute = 80))
    )
    healthConnectClient.insertRecords(listOf(bloodPressureRecord, heartRateRecord))
}

קריאת נתונים של מדדים חיוניים

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

דוגמה לקריאת נתונים מ-BloodPressureRecord:

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

    for (record in response.records) {
        // Process each blood pressure record
        val systolic = record.systolic
        val diastolic = record.diastolic
    }
}

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

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

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

• בקשות כתיבה באצווה: כדי לצמצם את התקורה של הקלט/פלט ולשמור על חיי הסוללה, כדאי לקבץ נקודות נתונים לקריאה אחת של insertRecords עם אצוות של עד 1,000 רשומות, במקום לכתוב כל נקודה בנפרד.
• כתיבה בתדירות גבוהה במהלך מעקב בזמן אמת: כדי לקבל עדכונים תכופים מחיישנים (כמו מכשירים למעקב רציף אחרי רמת הסוכר או מדי דופק), כדאי לכתוב נתונים בקבוצות במרווחים של עד 15 דקות. כך אפשר לאזן בין עדכונים בזמן אמת לבין חיסכון בסוללה.
• שימוש ב-WorkManager לסנכרון ברקע: השתמשו ב-WorkManager לכתיבה מושהית, כמו סנכרון נתונים ממכשיר נלווה או משירות לקצה העורפי. כדאי להגדיר מרווח של 15 דקות לכתיבה באצווה.
• הימנעו מכתיבת נתונים כפולים: השתמשו במזהי לקוח: כשיוצרים רשומות, הגדירו 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"
      )
  )

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

בדיקה

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

כלי אימות

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

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

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

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

פתרון בעיות

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