تطوير تجارب التمارين باستخدام Health Connect

يتوافق هذا الدليل مع الإصدار 1.1.0 من 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. بدلاً من ذلك، يمكنك تقديم بيانات ExerciseRoute عند إدراج ExerciseSessionRecord أو تعديله.

اعتبارات التطوير

غالبًا ما تحتاج تطبيقات تتبُّع التمارين إلى العمل لفترات طويلة، وغالبًا ما يكون ذلك في الخلفية عندما تكون الشاشة مطفأة. عند إنشاء ميزات التمارين، من المهم مراعاة كيفية إدارة التنفيذ في الخلفية وطلب الأذونات اللازمة لبيانات التمارين.

التنفيذ في الخلفية

تعمل تطبيقات التمارين الرياضية عادةً عندما تكون الشاشة مطفأة. في هذه الحالة، يجب استخدام:

• الخدمات التي تعمل في المقدّمة لجمع عينات من الموقع الجغرافي وأدوات الاستشعار
• WorkManager للكتابة المؤجَّلة أو المزامنة
• استراتيجيات تجميع البيانات لكتابة السجلات العادية

يجب الحفاظ على الاستمرارية من خلال الحفاظ على اتساق معرّف الجلسة في جميع عمليات الكتابة.

الأذونات

يجب أن يطلب تطبيقك أذونات Health Connect ذات الصلة قبل قراءة بيانات التمارين أو كتابتها. تشمل الأذونات الشائعة للتمارين الرياضية جلسات التمارين ومساراتها والمقاييس مثل معدّل نبضات القلب أو السرعة. ويتضمن ذلك ما يلي:

• جلسات التمارين الرياضية: أذونات القراءة وإذن التعديل لـ ExerciseSessionRecord.
• مسارات التمارين الرياضية: أذونات القراءة وإذن التعديل لـ "ExerciseRoute"
• معدّل نبضات القلب: أذونات القراءة والكتابة لـ "HeartRateRecord"
• السرعة: أذونات القراءة وإذن التعديل لـ "SpeedRecord"
• المسافة: أذونات القراءة وإذن التعديل لـ DistanceRecord.
• السعرات الحرارية: إذنَا القراءة والكتابة في "TotalCaloriesBurnedRecord"
• إجمالي الزيادة في الارتفاع: أذونات القراءة وإذن التعديل في ElevationGainedRecord
• Steps Cadence: أذونات القراءة وإذن التعديل لـ 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
        }
    }
}

أفضل الممارسات

اتّبِع الإرشادات التالية لتحسين موثوقية البيانات وتجربة المستخدم:

• كتابة البيانات بشكل متكرر أثناء التتبُّع النشط: بالنسبة إلى التتبُّع النشط، اكتب البيانات فور توفّرها أو بفاصل زمني أقصاه 15 دقيقة.
• استخدام WorkManager لعمليات المزامنة في الخلفية: استخدِم WorkManager لعمليات الكتابة المؤجَّلة. ننصحك بضبط الفاصل الزمني على 15 دقيقة لتحقيق التوازن بين البيانات في الوقت الفعلي وكفاءة البطارية.
• طلبات الكتابة المجمّعة: لا تكتب كل حدث من أحداث أداة الاستشعار بشكل فردي. تقسيم طلباتك إلى أجزاء يعالج تطبيق Health Connect ما يصل إلى 1000 سجلّ لكل طلب كتابة.
• الحفاظ على ثبات معرّفات الجلسات وفرادتها: استخدِم معرّفات متّسقة لجلساتك. إذا تم تعديل جلسة أو تحديثها، فإنّ استخدام المعرّف نفسه يمنع التعامل معها كجلسة جديدة منفصلة.
• استخدام ميزة "التجميع" لكل من أنواع البيانات ونقاط المسار: لتقليل عبء الإدخال/الإخراج والحفاظ على عمر البطارية، يمكنك تجميع نقاط البيانات في طلب 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 Toolbox: يمكنك استخدام هذا التطبيق المصاحب لفحص السجلات يدويًا وحذف بيانات الاختبار ومحاكاة التغييرات في قاعدة البيانات. إنها أفضل طريقة للتحقق من تخزين سجلاتك بشكل صحيح.
• اختبار الوحدات باستخدام FakeHealthConnectClient: استخدِم مكتبة الاختبار للتحقّق من كيفية تعامل تطبيقك مع الحالات الاستثنائية، مثل إلغاء الأذونات أو استثناءات واجهة برمجة التطبيقات بدون الحاجة إلى جهاز فعلي.

قائمة التحقّق من الجودة

البنية النموذجية

يتضمّن تنفيذ التمرين عادةً ما يلي:

تحديد المشاكل وحلّها

الخطوات الشائعة لتصحيح الأخطاء