التخطيط للأداء

ننصحك بالالتزام بإرشادات أفضل الممارسات التالية للتأكّد من أنّ تطبيقك يعمل بشكل جيد إلى جانب Health Connect.

كتابة البيانات

يجب ألا تطلب التطبيقات سوى كتابة بيانات مصادر خاصة في Health Connect.

إذا تم استيراد البيانات المتوفّرة في تطبيقك من تطبيق آخر، تقع على التطبيق الآخر مسؤولية كتابة بياناته الخاصة إلى Health Connect.

من الجيد أيضًا تنفيذ المنطق الذي يعالج استثناءات الكتابة مثل وجود البيانات خارج الحدود، أو خطأ في النظام الداخلي. يمكنك تطبيق استراتيجيات التراجع وإعادة المحاولة على آلية جدولة مهمة. إذا لم تنجح الكتابة إلى Health Connect في النهاية، تأكَّد من أنّ تطبيقك يمكنه تجاوز نقطة التصدير هذه. لا تنسَ تسجيل الأخطاء والإبلاغ عنها للمساعدة في التشخيص.

عند تتبع البيانات، هناك اثنين من الاقتراحات التي يمكنك اتباعها اعتمادًا على الطريقة التي يكتب بها تطبيقك البيانات.

التتبُّع بدون مفتاح

ويشمل ذلك التطبيقات التي تنفّذ أنشطة اللياقة البدنية السلبية أو تتبُّع الصحة، مثل تسجيل الخطوات أو معدّل نبضات القلب باستمرار في الخلفية.

يحتاج تطبيقك إلى كتابة البيانات بشكل دوري في Health Connect بالطرق التالية:

  • في كل مزامنة، اكتب فقط البيانات الجديدة وحدّث البيانات التي تم تعديلها منذ آخر مزامنة.
  • تقسيم الطلبات إلى 1000 سجلّ كحدّ أقصى لكل طلب كتابة
  • يمكنك استخدام WorkManager لجدولة مهام الخلفية الدورية، بفترة زمنية لا تقل عن 15 دقيقة.

  • تقييد تنفيذ المهام فقط عندما يكون الجهاز في وضع عدم النشاط ولا يكون طاقة بطارية الجهاز منخفضًا.

    val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

التتبُّع النشط

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

يُرجى التأكّد من أنّ تطبيقك لا يواصل تشغيل Health Connect طوال مدة الحدث.

يجب كتابة البيانات في Health Connect بإحدى الطريقتين التاليتين:

  • عليك مزامنة البيانات في Health Connect بعد اكتمال الحدث. على سبيل المثال، يمكنك مزامنة البيانات عندما ينهي المستخدم جلسة تمرين يتم تتبعها.
  • حدِّد موعدًا لمهمة لمرة واحدة باستخدام WorkManager لمزامنة البيانات لاحقًا.

معدل العينة

عند كتابة البيانات في Health Connect، استخدِم معدّلات العينات المناسبة للمساعدة في تقليل حِمل مساحة التخزين. على سبيل المثال، من المفيد التفكير في عدد المرات التي يلزم تسجيل بيانات عدد الخطوات فيها، أو نوع أنواع بيانات معدل العينة المرتبطة بتمرين نشط (مثل السرعة) التي تتطلبها.

لا يتطلب كل نوع بيانات نفس معدل العينة. هناك فائدة قليلة من تعديل بيانات عدد الخطوات كل ثانية، مقارنةً بالوتيرة الأقل تكرارًا، مثل كل 60 ثانية. ومع ذلك، قد تمنح معدلات العينات الأعلى المستخدمين نظرة أكثر تفصيلاً ودقة على بيانات الصحة واللياقة البدنية الخاصة بهم. تحتاج ترددات معدل العينة إلى تحقيق توازن بين التفاصيل والأداء.

مزامنة البيانات

تؤثّر العوامل التالية في عملية المزامنة.

انتهاء صلاحية الرمز المميّز

ونظرًا لانتهاء صلاحية الرمز المميّز للتغييرات غير المستخدَم في غضون 30 يومًا، عليك استخدام استراتيجية مزامنة تتجنّب فقدان المعلومات في مثل هذه الحالة. يمكن أن تتضمن استراتيجيتك المناهج التالية:

  • ابحث في متجر بيانات التطبيق عن آخر سجلّ تم استهلاكه والذي يحتوي أيضًا على id من Health Connect.
  • اطلب السجلات من Health Connect التي تبدأ بطابع زمني محدّد، ثم أدخِلها أو عدِّلها في مخزن بيانات تطبيقك.
  • اطلب الرمز المميز للتغييرات لحجزه في المرة التالية التي يكون مطلوبًا فيه.

استراتيجيات إدارة التغييرات المقترحة

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

  • قراءة جميع البيانات وإزالتها: هذه هي الإستراتيجية الأكثر مثالية.
    • تخزين الطابع الزمني لآخر مرة قرأ فيها المستخدمون البيانات من Health Connect.
    • عند انتهاء صلاحية الرمز المميز، يجب إعادة قراءة جميع البيانات من أحدث طابع زمني أو لآخر 30 يومًا. بعد ذلك، أزل التكرار من البيانات التي سبقت قراءتها باستخدام المعرفات.
    • يُنصح بتنفيذ معرِّفات العملاء لأنّها مطلوبة لتعديل البيانات.
  • قراءة البيانات فقط منذ آخر طابع زمني للقراءة: وينتج عن ذلك بعض الاختلافات في البيانات حول وقت انتهاء صلاحية الرمز المميّز للتغييرات، إلا أنّ الفترة الزمنية أقصر وقد تستغرق من بضع ساعات إلى يومَين.
    • تخزين الطابع الزمني لآخر مرة قرأ فيها المستخدمون البيانات من Health Connect.
    • عند انتهاء صلاحية الرمز المميّز، اقرأ جميع البيانات من هذا الطابع الزمني فصاعدًا.
  • حذف البيانات ثم قراءتها لآخر 30 يومًا. وهذا يتوافق بشكل أكبر مع ما يحدث عند عملية الدمج الأولى.
    • احذف جميع البيانات التي قرأها التطبيق من Health Connect خلال آخر 30 يومًا.
    • بعد الحذف، يُرجى قراءة كل هذه البيانات مرة أخرى.
  • قراءة البيانات لآخر 30 يومًا بدون إزالة أيّ تكرار. هذه هي الإستراتيجية الأقل مثالية، وتؤدي إلى عرض بيانات مكررة للمستخدمين.
    • احذف جميع البيانات التي قرأها التطبيق من Health Connect خلال آخر 30 يومًا.
    • السماح بالإدخالات المكررة.

الرموز المميزة لتغيير نوع البيانات

إذا كان تطبيقك يستهلك أكثر من نوع بيانات واحد بشكل مستقل، استخدِم رموزًا مميّزة للتغييرات منفصلة لكل نوع بيانات. لا تستخدم قائمة بأنواع بيانات متعددة مع Changes Sync API إلا إذا تم استهلاك أنواع البيانات هذه معًا أو لم يتم استهلاكها على الإطلاق.

القراءات التي تتم في المقدّمة

لا يمكن للتطبيقات قراءة البيانات من Health Connect إلا عندما تكون في المقدّمة. عند مزامنة البيانات من Health Connect، قد تنقطع إمكانية الوصول إلى Health Connect في أي وقت. على سبيل المثال، يجب أن يتعامل تطبيقك مع حالات الانقطاع في أثناء عملية المزامنة عند قراءة كمية كبيرة من البيانات الواردة من Health Connect، ومواصلة فتحه في المرة التالية التي يتم فيها فتح التطبيق.

توقيتات الاستيراد

بسبب عدم تمكُّن تطبيقك من تلقّي إشعارات بالبيانات الجديدة، تحقَّق من البيانات الجديدة على نقطتين:

  • في كل مرة يصبح فيها تطبيقك نشطًا في المقدّمة. في هذه الحالة، استخدِم أحداث مراحل النشاط
  • بشكل دوري، بينما يظل تطبيقك في المقدّمة. قم بإعلام المستخدمين عند توافر بيانات جديدة، مما يسمح لهم بتحديث الشاشة لتعكس التغييرات.

حدود المعدَّل

في حالات نادرة، يضع تطبيق Health Connect حدودًا لمعدّل الطلبات الواردة من تطبيقك. ويتم ذلك للحدّ من تأثير البطارية وأداء الجهاز.

  • ننصحك بشدة باتّباع إرشادات أفضل الممارسات لتجنُّب رفض طلبات تطبيقك بسبب تقييد المعدّل.
  • يجب أن تتسم التطبيقات بالمرونة مع تقييد المعدل. على سبيل المثال، يمكن كتابة البيانات في الخلفية أثناء المهمة الدورية التالية، في حال فشل الطلبات بسبب الحد من المعدل.

إعداد تطبيقك

تتضمّن العديد من التطبيقات خطوات إعداد مخصّصة، مثل تعليم الميزات أو طلب موافقة المستخدم. وننصح المطوّرين بشدة بتصدير نشاط الإعداد الذي يبدأه تطبيق Health Connect عندما يتفاعل المستخدم مع التطبيق للمرة الأولى. لإجراء ذلك، أضِف ما يلي في بيان التطبيق:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

ملاحظة: لا يتوفر دعم هذه الميزة بعد في نظام التشغيل Android 14 ولكنها ستصبح متوفرة قريبًا.

عندما يحاول مستخدم ربط تطبيقك بتطبيق Health Connect، يتم إطلاق النشاط الذي تم تصديره. يجب أن يؤدي هذا النشاط إلى ما يلي:

  • اعرض أي معلومات ذات صلة للمستخدم مثل توضيح البيانات التي تمت كتابتها أو قراءتها.
  • اطلب من المستخدم منح موافقته إذا لزم الأمر.
  • يمكنك تقديم طلب أذونات إلى Health Connect.
  • تنفيذ أي منطق آخر خاص بالتطبيق مثل جدولة مهمة دورية.
  • وبعد الانتهاء، اسمح للمستخدم برفض النشاط.

بالنسبة إلى التطبيقات التي لا تصدّر نشاط إعداد، ينقل Health Connect بدلاً من ذلك المستخدم إلى شاشة إدارة الأذونات بعد أن يحاول المستخدم ربط التطبيق. قد يكون ذلك مقبولاً للتطبيقات التي يكون فيها الحصول على الأذونات هو الشرط الأساسي الوحيد لنجاح عملية الدمج.

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