توسعه تجربه تمرین با Health Connect

این راهنما با Health Connect نسخه ۱.۱.۰ یا بالاتر سازگار است.

اگر می‌خواهید تجربه تمرین ورزشی در برنامه‌تان ایجاد کنید، می‌توانید از Health Connect برای انجام کارهایی مثل موارد زیر استفاده کنید:

• نوشتن داده‌های جلسات تمرین
• نوشتن مسیرهای تمرین
• نوشتن سنجه‌های تمرین مانند ضربان قلب، سرعت، و مسافت
• خواندن داده‌های تمرین از برنامه‌های دیگر

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

نمای کلی: ساختن ردیاب تمرین جامع

با دنبال کردن این مراحل اصلی، می‌توانید بااستفاده از Health Connect تجربه ردیابی تمرین جامعی بسازید:

• اجازه‌ها را به‌درستی براساس «اجازه‌های سلامت» پیاده‌سازی می‌کند.
• درحال ضبط جلسات بااستفاده از ExerciseSessionRecord.
• نوشتن مداوم داده‌های تمرین درطول جلسه.
• مدیریت صحیح اجرای پس‌زمینه برای تأیید ضبط مداوم داده‌ها.
• خواندن داده‌های جلسه برای خلاصه و تحلیل پس‌از تمرین.

این گردش کار امکان تعامل‌پذیری با دیگر برنامه‌های Health Connect را فراهم می‌کند و دسترسی به داده‌های تحت کنترل کاربر را تأیید می‌کند.

قبل‌از شروع

قبل‌از پیاده‌سازی ویژگی‌های تمرین:

• Health Connect را بااستفاده از وابستگی مناسب ادغام کنید.
• نمونه HealthConnectClient ایجاد کنید.
• تأیید کنید که برنامه‌تان جریان‌های اجازه زمان اجرا را براساس «اجازه‌های Health» پیاده‌سازی می‌کند.
• اگر گردش کارتان از 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 به‌روز نگه دارید، از 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
        }
    }
}

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

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

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

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

معماری معمول

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

عیب‌یابی

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