نقل بيانات Health Connect من Android 13 (APK) إلى Android 14 (إطار العمل)

سيتم تضمين Health Connect مع الإصدار 14 من Android كطبقة تخزين بيانات عامة لبيانات صحة المستهلكين، تكون محمية بأذونات دقيقة ويمكن الوصول إليها كأحد تطبيقات نظام Android (يُشار إليها في هذا المستند باسم "وحدة' ").

على المطوّرين اعتبار حزمة APK لتطبيق Health Connect (الإصدار 13 من نظام التشغيل Android) بمثابة طبقة Compatiblity لنموذج الإطار. سيحتفظ نموذج إطار العمل بالميزات نفسها بالكامل في حزمة APK السابقة.

أثناء عملية الانتقال من Android 13 إلى 14، من المهم جدًا أن تظل تجربة المستخدم سلسة وسهلة قدر الإمكان.

يوضّح هذا المستند خطة نقل البيانات، ويقدّم بعض الأمثلة على سيناريوهات نقل البيانات، ويسرد التغييرات التي تم إجراؤها على حزمة تطوير البرامج (SDK) من Jetpack، ما يسهّل الوصول إلى واجهة برمجة التطبيقات Health Connect API.

خطة نقل البيانات

  1. بعد طرح الإصدار 14 من Android، ستتوقف Google عن توفير Health Connect كتطبيق نظام Android.
  2. وبعد ذلك، ستتم إضافة البيانات من حِزمة APK بعد أن تصبح الميزات متطابقة.
  3. ستستهدف جميع نقاط الدخول واجهة مستخدم تطبيق النظام.
  4. ستبدأ عملية نقل البيانات. أثناء تقدّم عملية نقل البيانات، سيتم تعليق واجهات برمجة تطبيقات الوحدات مع ظهور الحالة "عملية نقل البيانات قيد التقدّم". وسيظهر هذا الرمز أيضًا في واجهة مستخدم Health Connect.
  5. بعد اكتمال نقل البيانات، يمكن إلغاء تثبيت حزمة APK.

أمثلة على سيناريوهات نقل البيانات

في ما يلي بعض الأمثلة على السيناريوهات التي توضّح عملية نقل نوعَي البيانات interval وseries:

المثال 1: الركض (بيانات الفواصل الزمنية)

جمع مستخدم سجلات الركض لمدة 10 سنوات لمدة ساعة واحدة كل يوم. ويعادل ذلك:

  • سجلّات جلسات التمارين الرياضية: 365 * 10 * 1
  • الخطوات: 365 * 10 * 1
  • السعرات الحرارية: 365 * 10 * 1
  • الإجمالي = 365 * 10 * 3 (365 * 30) = 10,150

بما أنّ 1 قطعة تساوي 3,000 سجلّ، تبلغ البيانات أعلاه إجمالاً حوالي 4 قطع.

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

المثال 2: معدّل نبضات القلب (بيانات السلسلة)

جمع مستخدم بيانات معدّل نبضات القلب لمدة 5 سنوات (مع إنشاء سجلّ كل دقيقة) يبلغ مجموعها 2,628,000 سجلّ.

عند تضمين 3,000 سجلّ في كل مجموعة، يتم توزيع البيانات على 876 مجموعة. بما أنّ إدراج قطعة واحدة يستغرق ثانية واحدة تقريبًا، سيتم نقل البيانات في أقل من 15 دقيقة.

مسار نقل البيانات المقترَح

قرّرنا اختيار نقل البيانات على الفور. من الناحية العملية، يعني ذلك أنّ ملف APK سيصبح غير نشط فور ترقية الجهاز إلى Android 14، مع الحد الأدنى من تدخل المستخدم.

لنلقِ نظرة على خطوات نقل البيانات الأساسية:

  1. يُجري المستخدم ترقية لجهازه إلى الإصدار 14 من Android.
  2. يوجّه Jetpack 14 المستخدم إلى واجهات برمجة تطبيقات الوحدات، ويحظرها أثناء عملية نقل البيانات.
  3. تبدأ عملية نقل البيانات عندما يكون إصدار الوحدة متوافقًا من حيث الميزات مع ملف APK، أي أنّ إصدار الوحدة يحتوي على مجموعة الميزات نفسها أو أكثر. بعد بدء عملية نقل البيانات، ينقل حِزمة APK الأذونات والبيانات.
    1. إذا لم يكن كلا الإصدارَين متوافقَين من حيث الميزات، يجب ترقية إصدار الوحدة. بعد اكتمال الترقية، ستبدأ عملية نقل البيانات.
  4. بعد اكتمال عملية نقل البيانات، يتم تغيير الحالة إلى "نقل البيانات مكتمل"، ويتم إلغاء حظر واجهات برمجة التطبيقات الخاصة بالوحدة.
  5. يمكن الآن إلغاء تثبيت حزمة APK.

عناصر واجهة مستخدم نقل البيانات

تعرِض وحدة الإطار العمل الشاشات التالية لأغراض تنمية وعي المستخدمين، قبل نقل البيانات وأثناءه:

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

يجب تحديث الهاتف


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

مطلوب تحديث حزمة APK


الشكل 3: يظهر مؤشر تدوير أثناء عملية نقل البيانات، مع نص يوضّح أنّه تتم مزامنة البيانات:

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

البيانات التي تمّت إزالة تكرارها

إذا بدأت وحدة إطار العمل في الحصول على البيانات والأذونات قبل حدوث أي عملية نقل بيانات أو استعادة مستندات مستندة إلى السحابة الإلكترونية، تنطبق القواعد التالية.

الأذونات

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

البيانات

أثناء نقل البيانات، يتم تجاهل البيانات المكرّرة التي تأتي من حزمة APK. وتُمنَح الأولوية للبيانات الأحدث من الوحدة.

تتم إزالة تكرار البيانات في clientRecordId إذا قدّم العميل معرّف السجلّ. وإذا لم يكن كذلك، يتم التعامل مع الفواصل الزمنية (startTime وendTime للسجلّات الداخلية وtime للسجلّات الفورية) كمفتاح، إلى جانب نوع البيانات واسم حزمة التطبيق.

التغييرات في حزمة تطوير البرامج (SDK) من Jetpack

تُعدّ حزمة تطوير البرامج (SDK) من Jetpack نقطة الدمج المشتركة لكلّ من حزمة APK الخاصة بتطبيق Health Connect وواجهات برمجة تطبيقات إطار عمل Health Connect.

يمكن لمصنّعي المعدّات الأصلية بدء الدمج مع Jetpack 13 لكي تتمكّن من استخدام المكتبة الجديدة وتجميعها ضمن Android 14 عندما يصبح متاحًا.

سنطرح إصدارًا جديدًا من حزمة SDK يتيح الانتقال إلى Android 14. سيكون عليك إجراء بعض التغييرات على عملية الدمج الحالية ل ضمان عملية انتقال سلسة.

بيان الأذونات

في الإصدار 13 من Android، يمكنك تقديم بيان الأذونات باستخدام تنسيق مخصّص للأذونات فيملف موارد مرتبط بالبيان:

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

لتتوافق التطبيقات مع Android 14، على المطوّرين الانتقال إلى التنسيق العادي للسماح:

#AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP” />
<uses-permission android:name=”android.permission.health.READ_WEIGHT” />
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT” />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

فتح Health Connect

تتضمّن معظم التطبيقات التابعة لجهات خارجية زرًا يفتح تطبيق Health Connect، مثل الزر "إدارة الإذن بالوصول" في Fitbit.

في Android 13، يمكنك فتح تطبيق Health Connect باستخدام اسم الحزمة أو من خلال الإجراء androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

في Android 14، عليك استخدام إجراء نية محدّد في حزمة تطوير البرامج (SDK) من Jetpack، والذي يتضمّن قيمًا مختلفة استنادًا إلى إصدار Android الذي يعمل عليه:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

الحصول على برنامج Health Connect

لقد أنشأنا واجهة برمجة تطبيقات واحدة باسم sdkStatus، وهي متوفّرة في Jetpack 11، بهدف استبدال واجهتَي برمجة تطبيقات أخريتَين تم إيقافهما نهائيًا، وهما IsSdkSupported() و isProviderAvailable().

التغييرات في Session record API

تم حذف أربعة أنواع فرعية من ExerciseSession كجزء من الإصدار alpha10:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

كما هو الحال مع ExerciseSessionRecord، سيصبح SleepStage نوعًا فرعيًا من SleepSession.

سيتم طرح كلّ من الأنواع الفرعية ExerciseSessionRecord وتغييرات SleepSession كجزء من تحديث حزمة تطوير البرامج (SDK) في نيسان (أبريل).

تعديل نوع جلسة التمرين الرياضي

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

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

أنواع الاستبدال:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

معالجة سجلّ التغييرات

لن يتم نقل سجلّات التغييرات كجزء من عملية التبديل من حِزم APK إلى Android 14.

بعد اكتمال عملية نقل البيانات، ستبدأ في تلقّي استثناءات TOKEN_EXPIRED أو TOKEN_INVALID. يجب التعامل مع هذه الأخطاء بالطرق التالية (بترتيب الاختيار المفضّل):

1. قراءة جميع البيانات وإزالة تكرارها منذ الطابع الزمني "آخر قراءة" أو في آخر 30 يومًا

تخزين طابع زمني لآخر مرة قرأ فيها تطبيق البيانات من Health Connect عند انتهاء صلاحية الرمز المميّز، يجب إعادة قراءة البيانات إما من هذه القيمة أو من آخر 30 يومًا (أيهما أقلّ)، وإزالة تكرارها مقارنةً بالبيانات التي تمت قراءتها سابقًا باستخدام معرّف UUID.

2. قراءة البيانات منذ الطابع الزمني "لآخر قراءة"

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

3. حذف البيانات وإعادة قراءتها لآخر 30 يومًا

حذف جميع البيانات التي تم قراءتها من Health Connect خلال آخر 30 يومًا، وقراءة كل هذه البيانات مرة أخرى (مثلما يتم عند دمج التطبيقات مع Health Connect لأول مرة)

‫4. عدم اتّخاذ أي إجراء (أي إعادة قراءة البيانات لآخر 30 يومًا وعدم إزالة تكراراتها)

يجب استخدام هذا الإجراء كحلّ أخير، مع المخاطر المرتبطة بعرض data مكرّرة. على المطوّرين استكشاف الخيارات من 1 إلى 3 بدلاً من ذلك، لأنّه من المفترض أن تكون معرّفات UUID متوفّرة.

اختبار واجهات برمجة تطبيقات Android 14 باستخدام حزمة تطوير البرامج (SDK) من Jetpack

من المقرّر إطلاق حزمة تطوير البرامج (SDK) لنظام التشغيل Android 14 من Jetpack في 7 حزيران (يونيو) 2023، إلى جانب الإصدار التجريبي 3 من Android 14. عليك بدء تجميع تطبيقك ليعمل على الإصدار Android 14 حتى تتمكّن من استخدام حزمة تطوير البرامج (SDK) Jetpack لنظام التشغيل Android 14.

إذا أردت اختبار الحلّ على إصدارات Android Developer Preview قبل 7 حزيران (يونيو)، يُرجى التواصل مع جهة التواصل المعيّنة لك في Google للحصول على المساعدة.

إذا كنت تريد اختبار الحلّ في الإصدار التجريبي 3، عليك إجراء التغييرات التالية في حزمة APK:

  1. اضبط compileSDKPreview = UpsideDownCake.
  2. عدِّل البيان لتضمين نية لنظام التشغيل Android 14:
# AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP”/>
<uses-permission android:name=”android.permission.health.READ_WEIGHT”/>
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT”/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
      <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
      </intent-filter>
</activity-alias>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

تخصيصات المصنّع الأصلي للجهاز

في الإصدار 14 من Android، يمكنك العثور على عناصر التحكّم في إدارة البيانات والخصوصية في Health Connect ضمن "إعدادات النظام".

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

للحصول على مستندات حول تصميم المصنّع الأصلي للجهاز، يمكنك الرجوع إلى مستندات Health Connect Google Mobile Services. قد يُطلب منك تسجيل الدخول إلى Google Developer Console لعرض الصفحة.