تطوير تجارب التمارين باستخدام 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
• إيقاع الخطوات: أذونات القراءة والكتابة لبيانات StepsCadenceRecord.
• الطاقة: أذونات القراءة والكتابة في 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. ابدأ جمع بيانات نوع البيانات وبيانات نظام تحديد المواقع العالمي (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، استخدِم 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: استخدِم مكتبة الاختبار للتحقّق من طريقة تعامل تطبيقك مع الحالات الحدّية، مثل إلغاء الإذن أو استثناءات واجهة برمجة التطبيقات، بدون الحاجة إلى جهاز فعلي.

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

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

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

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

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