פיתוח חוויות אימון באמצעות Health Connect

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

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

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

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

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

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

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

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

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

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

קונספטים מרכזיים

אפליקציית Health Connect מייצגת נתוני אימון באמצעות כמה רכיבי ליבה. ExerciseSessionRecord משמש כרשומה מרכזית של אימון כושר, והוא מכיל פרטים כמו שעת התחלה או שעת סיום וסוג האימון. במהלך סשן, המערכת יכולה לתעד סוגים שונים של נתונים, כמו HeartRateRecord או SpeedRecord. בפעילויות בחוץ, ExerciseRoute שומרת נתוני GPS שמקושרים לסשן המתאים.

סשנים של פעילות גופנית

‫ExerciseSessionRecord הוא הרשומה המרכזית של נתוני אימון כושר, שמייצגת אימון יחיד. כל רשומה מכילה את הפרטים הבאים:

• startTime
• endTime
• exerciseType
• מטא-נתונים אופציונליים של הסשן (שם, הערות)

ExerciseSessionRecord יכול להכיל גם מסלולי אימון, הקפות ופלחים כחלק מהנתונים שלו. בנוסף, יכול להיות שסוגי נתונים אחרים כמו HeartRateRecord או SpeedRecord יוקלטו במהלך הפגישה וישויכו אליה.

סוגי נתונים משויכים

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

• ‫HeartRateRecord: מייצג סדרה של מדידות דופק.
• ‫SpeedRecord: מייצג סדרה של מדידות מהירות.
• ‫DistanceRecord: מייצג את המרחק שעבר בין קריאות.
• ‫TotalCaloriesBurnedRecord: מייצג את סך הקלוריות שנשרפו בין הקריאות.
• ‫ElevationGainedRecord: מייצג את העלייה בגובה בין הקריאות.
• ‫StepsCadenceRecord: מייצג את קצב הצעדים בין הקריאות.
• ‫PowerRecord: מייצג את תפוקת הכוח בין הקריאות, נפוץ בפעילויות כמו רכיבה על אופניים.

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

מסלולי אימונים

אתם יכולים לשייך מסלול לאימונים בחוץ באמצעות ExerciseRoute. מסלולים מורכבים מאובייקטים עוקבים של ExerciseRoute.Location, שכל אחד מהם מכיל:

• קו רוחב וקו אורך
• גובה אופציונלי
• כיוון אופציונלי
• מידע על דיוק
• חותמת זמן

קישור מסלולי סשנים

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

שיקולי פיתוח

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

הרצה ברקע

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

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

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

הרשאות

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

• אימונים: הרשאות קריאה וכתיבה ל-ExerciseSessionRecord.
• מסלולי אימון: הרשאות קריאה וכתיבה ל-ExerciseRoute.
• דופק: הרשאות קריאה וכתיבה ל-HeartRateRecord.
• מהירות: הרשאות קריאה וכתיבה ל-SpeedRecord.
• מרחק: הרשאות קריאה וכתיבה ל-DistanceRecord.
• קלוריות: הרשאות קריאה וכתיבה לTotalCaloriesBurnedRecord.
• סה"כ עלייה: הרשאות קריאה וכתיבה ל-ElevationGainedRecord.
• קצב הצעדים: הרשאות קריאה וכתיבה עבור StepsCadenceRecord.
• Power: הרשאות קריאה וכתיבה ל-PowerRecord.
• שלבים: הרשאות קריאה וכתיבה עבור StepsRecord.

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

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class),
  HealthPermission.getReadPermission(ExerciseRoute::class),
  HealthPermission.getWritePermission(ExerciseRoute::class),
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(SpeedRecord::class),
  HealthPermission.getWritePermission(SpeedRecord::class),
  HealthPermission.getReadPermission(DistanceRecord::class),
  HealthPermission.getWritePermission(DistanceRecord::class),
  HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::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)
  }
}

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

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

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

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

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

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

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

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

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

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

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

הטמעה של אימון

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

התחלת הסשן

כדי ליצור אימון כושר חדש:

1. יצירת מזהה סשן ייחודי: צריך לוודא שהמזהה הזה יציב. אם התהליך של האפליקציה נקטע ומופעל מחדש, אתם צריכים להיות מסוגלים להמשיך להשתמש באותו מזהה כדי למנוע סשנים מקוטעים.
2. כדי למנוע כפילויות במהלך ניסיונות חוזרים של סנכרון, צריך להגדיר metadata.clientRecordId.
3. כותבים ExerciseSessionRecord: כוללים את שעת ההתחלה.
4. מתחילים לאסוף נתונים מסוג Data ונתוני GPS: מתחילים לאסוף את הנתונים האלה רק אחרי שההפעלה של רשומת הסשן הושלמה בהצלחה.

דוגמה:

val sessionId = UUID.randomUUID().toString()
val sessionClientId = UUID.randomUUID().toString()

val session = ExerciseSessionRecord(
    id = sessionId,
    exerciseType = ExerciseType.EXERCISE_TYPE_RUNNING,
    startTime = Instant.now(),
    endTime = null,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))

תיעוד של מסלולי אימון

מידע נוסף על הנחיות לקריאה זמין במאמר קריאת נתונים גולמיים.

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

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

בדוגמה הבאה אפשר לראות איך להקליט בקבוצות:

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

סיום סשן

אחרי שמפסיקים את איסוף הנתונים:

• עדכון הרשומה: האפליקציה מעדכנת את ExerciseSessionRecord באמצעות endTime.
• השלמת הנתונים: אפשר לחשב ערכי סיכום (כמו מרחק כולל או קצב ממוצע) ולכתוב אותם כרשומות נוספות.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

קריאת נתוני אימון

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

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

קריאת סשנים

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

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

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

קריאת מסלולים

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

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

קריאת סוגי נתונים

כדי לקרוא נתונים ספציפיים ברמת פירוט גבוהה (כמו דופק) שהתרחשו במהלך אימון, צריך להשתמש בפרמטרים startTime ו-endTime של האימון כדי לסנן את הבקשה לסוג הנתונים הזה.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.records) {
        for (sample in heartRateRecord.samples) {
            val bpm = sample.beatsPerMinute
        }
    }
}

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

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

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

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

• אימות הדיוק של ה-GPS: סינון דגימות GPS עם רמת דיוק נמוכה (לדוגמה, נקודות עם רדיוס דיוק אופקי גבוה) לפני הכתיבה אל ExerciseRoute כדי לוודא שהמפה נראית נקייה ומקצועית.

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

• צריך לספק הסברים ברורים למה נדרשת הרשאה: בתהליך Permission.createIntent צריך להסביר למה האפליקציה צריכה גישה לנתונים בריאותיים, למשל: "כדי למפות את הריצות שלך ולחשב את מספר הקלוריות שנשרפו".

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

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

• התאמת חותמות הזמן לתדירות החיישנים: כדי לשמור על רמת דיוק גבוהה של הנתונים, צריך להתאים את חותמות הזמן של הרשומה לתדירות בפועל של החיישנים (לדוגמה, 1Hz ל-GPS).

בדיקה

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

כלי אימות

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

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

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

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

פתרון בעיות

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

• בדיקת מצב ההרשאה: תמיד צריך להתקשר אל getPermissionStatus() לפני שמנסים לבצע פעולת קריאה או כתיבה. המשתמשים יכולים לבטל את ההרשאות בהגדרות המערכת בכל שלב.
• אימות מצב ההפעלה: אם האפליקציה לא אוספת נתונים ברקע, צריך לוודא שהצהרתם על ההרשאות הנכונות ב-AndroidManifest.xml ושהמשתמש לא העביר את האפליקציה למצב 'הגבלת השימוש בסוללה'.