توسعه تجربه تمرین با 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 درنظر گرفته نمی‌شوند. درعوض، هنگام درج یا به‌روزرسانی ExerciseSessionRecord، داده‌های ExerciseRoute را ارائه می‌کنید.

ملاحظات توسعه

برنامه‌های ردیابی تمرین اغلب باید برای مدت طولانی، و معمولاً در پس‌زمینه و زمانی که صفحه خاموش است، اجرا شوند. هنگام ساختن ویژگی‌های تمرین، مهم است که نحوه مدیریت اجرای پس‌زمینه‌ای و درخواست اجازه‌های لازم برای داده‌های تمرین را درنظر بگیرید.

اجرا در پس‌زمینه

برنامه‌های تمرین معمولاً با صفحه خاموش اجرا می‌شوند. وقتی در این حالت هستید، باید از موارد زیر استفاده کنید:

• سرویس‌های پیش‌زمینه‌ای برای مکان و نمونه‌برداری حسگر
• WorkManager برای نوشتن یا همگام‌سازی به‌تعویق‌افتاده
• استراتژی‌های دسته‌بندی برای نوشتن گزارش‌های معمولی

با یکسان نگه داشتن شناسه جلسه در همه نوشتن‌ها، تداوم را حفظ کنید.

اجازه‌ها

برنامه شما باید قبل‌از خواندن یا نوشتن داده‌های تمرین، اجازه‌های مربوط به Health Connect را درخواست کند. اجازه‌های رایج برای تمرین‌ها شامل جلسات تمرین، مسیرهای تمرین، و سنجه‌هایی مثل ضربان قلب یا سرعت می‌شود. این شامل موارد زیر می‌شود:

• جلسه‌های تمرین: اجازه‌های خواندن و نوشتن برای ExerciseSessionRecord.
• مسیرهای تمرین: اجازه‌های خواندن و نوشتن برای ExerciseRoute.
• ضربان قلب: اجازه‌های خواندن و نوشتن برای HeartRateRecord.
• سرعت: اجازه‌های خواندن و نوشتن برای SpeedRecord.
• فاصله: اجازه‌های خواندن و نوشتن برای DistanceRecord.
• کالری: اجازه‌های خواندن و نوشتن برای TotalCaloriesBurnedRecord.
• ارتفاع صعودشده: اجازه‌های خواندن و نوشتن برای ElevationGainedRecord.
• سرعت قدم‌ها: اجازه‌های خواندن و نوشتن برای StepsCadenceRecord.
• قدرت: اجازه‌های خواندن و نوشتن برای 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. شروع جمع‌آوری «نوع داده» و داده‌های 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.activelyRecorded(clientRecordId = sessionClientId, device = Device(type = Device.TYPE_PHONE)),
)

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

ضبط مسیرهای تمرین

برای کسب اطلاعات بیشتر درباره راهنمایی خواندن، خواندن داده‌های خام را ببینید.

هنگام ضبط مسیر تمرین، باید داده‌هایتان را دسته‌بندی کنید. این یعنی به‌جای اینکه هر نقطه 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
        }
    }
}

روال‌های مطلوب

برای بهبود قابلیت اطمینان داده‌ها و تجربه کاربری، این رهنمودها را دنبال کنید:

• نوشتن مکرر درطول ردیابی فعال: برای ردیابی فعال، داده‌ها را به‌محض دردسترس قرار گرفتن یا در حداکثر فاصله زمانی ۱۵ دقیقه بنویسید.
• استفاده از WorkManager برای همگام‌سازی‌های پس‌زمینه: از WorkManager برای نوشتن‌های به‌تعویق‌افتاده استفاده کنید. برای ایجاد تعادل بین داده‌های هم‌زمان و کارایی باتری، فاصله زمانی ۱۵ دقیقه‌ای را هدف قرار دهید.
• درخواست‌های نوشتن دسته‌ای: هر رویداد حسگر را به‌صورت جداگانه ننویسید. درخواست‌هایتان را دسته‌بندی کنید. ‫Health Connect در هر درخواست نوشتن حداکثر ۱۰۰۰ سابقه را مدیریت می‌کند.
• شناسه‌های جلسه را ثابت و یکتا نگه دارید: از شناسه‌های یکسان برای جلسات خود استفاده کنید. اگر جلسه‌ای ویرایش یا به‌روز شود، استفاده از همان شناسه باعث می‌شود که به‌عنوان جلسه جدید و جداگانه درنظر گرفته نشود.
• استفاده از دسته‌بندی برای هر دو نوع داده و نقاط مسیر: برای کاهش سربار ورودی/خروجی و حفظ عمر باتری، نقاط داده خود را به‌جای نوشتن هر نقطه به‌صورت جداگانه، در یک تماس 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 را در برنامه‌تان درستی‌سنجی کنید.

بازبینه کیفیت

معماری معمول

پیاده‌سازی تمرین معمولاً شامل موارد زیر است:

عیب‌یابی

مراحل رایج اشکال‌زدایی