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

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

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

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

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

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

1. بعد طرح الإصدار Android 14، ستوفّر 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,950

بما أنّ كل جزء يعادل 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. بعد اكتمال عملية نقل البيانات، تتغيّر الحالة إلى Migration Complete، ويتم إلغاء حظر واجهات برمجة التطبيقات الخاصة بالوحدة.
5. يمكن الآن إلغاء تثبيت حزمة APK.

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

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

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

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

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

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

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

الأذونات

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

البيانات

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

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

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

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

يمكن لمصنّعي المعدات الأصلية البدء في الدمج مع Jetpack 13، وبذلك عندما يصبح Jetpack 14 متاحًا، سيصبح بإمكانك استخدام المكتبة الجديدة وتجميعها ضمن 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.

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

في نظام التشغيل Android 14، عليك استخدام إجراء Intent محدّد في حزمة تطوير البرامج (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 إلى نظام التشغيل Android 14.

بعد اكتمال عملية نقل البيانات، ستبدأ في تلقّي استثناءات 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 باستخدام حزمة تطوير البرامج (SDK) من Jetpack

من المقرر إطلاق حزمة تطوير البرامج (SDK) لنظام التشغيل Android 14 Jetpack في 7 يونيو 2023، وذلك بالتزامن مع الإصدار التجريبي 3 من نظام التشغيل Android 14. يجب البدء بتجميع تطبيقك باستخدام Android 14 لتتمكّن من استخدام حزمة تطوير البرامج (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. قد يُطلب منك تسجيل الدخول إلى Google Developers لعرض الصفحة.