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

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

على المطوّرين اعتبار حزمة APK لتطبيق Health Connect (Android 13) طبقة توافق مع الأنظمة القديمة لنموذج إطار العمل. سيحتفظ نموذج إطار العمل بميزة التكافؤ بنسبة 100% مع حزمة APK السابقة.

خلال عملية الانتقال من نظام التشغيل Android 13 إلى نظام التشغيل Android 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) = 10150

بالنظر إلى أن مقطعًا واحدًا يساوي 3000 سجل، فإن إجمالي البيانات أعلاه يبلغ حوالي 4 قطع.

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

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

جمع المستخدم 5 سنوات من بيانات معدل ضربات القلب (مع إنشاء سجل كل دقيقة) يبلغ مجموعه 2628000 سجل.

عند 3000 سجل لكل مقطع، يتم توزيع البيانات على 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. سيكون عليك إجراء بعض التغييرات على عملية الدمج الحالية لضمان عملية انتقال سلسة

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

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

#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>

لإتاحة الإصدار 14 من نظام التشغيل Android، على المطوّرين استخدام تنسيق الأذونات العادي:

#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().

التغييرات في واجهة برمجة التطبيقات لسجلّ الجلسة

تم حذف أربعة أنواع فرعية من 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 إلى الإصدار 14 من نظام التشغيل Android.

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

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

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

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

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

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

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

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

يجب استخدام هذا كحل أخير، مع المخاطر المرتبطة بعرض البيانات المكررة. يجب على المطورين بدلاً من ذلك استكشاف الخيارات 1-3، نظرًا لأن أرقام التعريف الفريدة العالمية (UUID) يجب أن تكون موجودة بالفعل.

اختبار واجهات برمجة تطبيقات Android 14 باستخدام Jetpack SDK

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

إذا أردت اختبار حلك مقارنةً بإصدارات "معاينة مطوّري برامج Android" قبل 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>

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

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

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

للحصول على مستندات حول أنماط المصنّع الأصلي للجهاز، يُرجى الاطّلاع على مستندات خدمات Google للأجهزة الجوّالة في Health Connect.