פיתוח חוויות אימון באמצעות 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.

val permissions =
    setOf(
        HealthPermission.getReadPermission(ExerciseSessionRecord::class),
        HealthPermission.getWritePermission(ExerciseSessionRecord::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)
    )
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_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 type ונתוני GPS: מתחילים לאסוף את הנתונים האלה רק אחרי שההפעלה של רשומת הסשן הושלמה בהצלחה.

דוגמה:

val sessionClientId = UUID.randomUUID().toString()
val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)

val session =   ExerciseSessionRecord(
    startTime = startTime,
    startZoneOffset = zoneOffset,
    endTime = startTime.plusSeconds(3600),
    endZoneOffset = zoneOffset,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))
HealthConnectManager.kt

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

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

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

זה חשוב כי בכל פעם שהאפליקציה קוראת מ-Health Connect או כותבת ל-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, אתם יכולים להשתמש ב-ChangeLogs. כך אפשר לאחזר רשימה של רשומות שנוספו, עודכנו או נמחקו מאז נקודת זמן ספציפית. זה יעיל יותר ממעקב ידני אחרי שינויים או מקריאה חוזרת של כל הנתונים. מידע נוסף זמין במאמר סנכרון נתונים עם 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 לסנכרון ברקע: שימוש ב-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 כדי להסביר למה האפליקציה צריכה גישה לנתונים בתחום הבריאות. לדוגמה: 'כדי לעקוב אחרי המגמות של לחץ הדם ולספק תובנות'.
• תמיכה בהשהיה ובהמשך: מוודאים שהאפליקציה מטפלת בהשהיות בצורה נכונה. כשמשתמש משהה את הפעילות, צריך להפסיק לאסוף נקודות מסלול וסוגי נתונים כדי שהקצב הממוצע ומשך הפעילות יישארו מדויקים.
• בדיקת סשנים ארוכים: מעקב אחרי צריכת הסוללה במהלך סשנים שנמשכים כמה שעות כדי לוודא שמרווח האצווה ושימוש בחיישן לא מרוקנים את הסוללה של המכשיר.
• התאמת חותמות הזמן לקצב החיישנים: כדי לשמור על רמת מהימנות גבוהה של הנתונים, צריך להתאים את חותמות הזמן של הרשומה לתדירות בפועל של החיישנים.

בדיקה

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

כלי אימות

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

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

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

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

פתרון בעיות

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