انتقال Health Connect از Android 13 (بسته APK) به Android 14 (چارچوب)

Health Connect با Android 14 به‌عنوان لایه ذخیره‌سازی داده‌های مشترک برای داده‌های سلامتی و تناسب اندام مصرف‌کننده بسته‌بندی خواهد شد، که با اجازه‌های جزئی محافظت می‌شود و به‌عنوان برنامه سیستم Android (که در سراسر این سند به‌عنوان ماژول «چارچوب» نامیده می‌شود) قابل‌دسترسی است.

توسعه‌دهندگان باید Health Connect APK (نسخه Android 13) را به‌عنوان لایه سازگاری با نسخه‌های قدیمی برای مدل چارچوب درنظر بگیرند. مدل چارچوب، ۱۰۰٪ برابری ویژگی را با APK قبلی خود حفظ خواهد کرد.

درطول انتقال از Android 13 به 14، بسیار مهم است که تجربه کاربری تا حد امکان روان و شهودی باقی بماند.

این سند طرح انتقال را شرح می‌دهد، چند نمونه سناریو انتقال ارائه می‌دهد، و تغییرات Jetpack SDK را که دسترسی به Health Connect API را تسهیل می‌کند فهرست می‌کند.

طرح انتقال

1. وقتی Android 14 منتشر شود، Google ارائه Health Connect را به‌عنوان برنامه سیستم Android تغییر خواهد داد.
2. سپس، پس‌از دستیابی به برابری ویژگی، داده‌ها از APK پر خواهند شد.
3. همه نقاط ورودی، واسط کاربر برنامه سیستم را هدف قرار خواهند داد.
4. انتقال داده‌ها آغاز خواهد شد. درطول فرایند انتقال، میاناهای برنامه‌سازی کاربردی واحد با وضعیت «انتقال درحال انجام است» تعلیق خواهند شد. این در واسط کاربر Health Connect نیز قابل‌مشاهده خواهد بود.
5. پس‌از تکمیل انتقال، APK را می‌توان حذف نصب کرد.

سناریوهای نمونه انتقال

در اینجا چند سناریو نمونه آورده شده است که فرایند انتقال را برای هر دو نوع داده interval و series توضیح می‌دهد:

مثال ۱ - دویدن (داده‌های فاصله‌ای)

کاربری ۱۰ سال سابقه دویدن به‌مدت ۱ ساعت در روز را جمع‌آوری کرده است. این برابر است با:

• سوابق جلسه تمرین: ۳۶۵ * ۱۰ * ۱
• مراحل: ۳۶۵ * ۱۰ * ۱
• کالری: ۳۶۵ * ۱۰ * ۱
• مجموع = ۳۶۵ * ۱۰ * ۳ (۳۶۵ * ۳۰) = ۱۰٬۹۵۰

با فرض اینکه هر تکه معادل ۳۰۰۰ رکورد باشد، داده‌ها درمجموع حدود ۴ تکه می‌شود.

آزمایش داخلی ما تأیید کرده است که درج یک تکه معمولی تقریباً یک ثانیه طول می‌کشد، بنابراین داده‌های موجود در مثال تقریباً در ۴ ثانیه منتقل می‌شوند.

مثال ۲ - ضربان قلب (داده‌های سری)

کاربری داده‌های ضربان قلب ۵ سال را جمع‌آوری کرده است (با سابقه‌ای که هر دقیقه ایجاد می‌شود) که درمجموع ۲٬۶۲۸٬۰۰۰ سابقه می‌شود.

با ۳۰۰۰ رکورد در هر بخش، داده‌ها در ۸۷۶ بخش توزیع می‌شوند. با فرض اینکه درج هر تکه تقریباً یک ثانیه طول می‌کشد، داده‌ها در کمتر از ۱۵ دقیقه منتقل می‌شوند.

جریان انتقال پیشنهادی

تصمیم گرفته‌ایم انتقال فوری را انتخاب کنیم. در عمل، این یعنی به‌محض اینکه دستگاه به Android 14 ارتقا یابد، APK با حداقل مداخله کاربر غیرفعال خواهد شد.

جریان انتقال سطح بالا در اینجا آمده است:

1. کاربر دستگاهش را به Android 14 ارتقا می‌دهد.
2. ‫Jetpack 14 کاربر را به میاناهای برنامه‌سازی کاربردی ماژول هدایت می‌کند و آن‌ها را درحین انجام انتقال مسدود می‌کند.
3. فرایند انتقال زمانی شروع می‌شود که نسخه واحد ازنظر ویژگی با APK سازگار باشد - به‌عبارت دیگر، نسخه واحد شامل همان مجموعه ویژگی‌ها یا بیشتر باشد. وقتی فرایند انتقال شروع شد، APK اجازه‌ها و داده‌ها را منتقل می‌کند.
   1. اگر هر دو نسخه ازنظر ویژگی سازگار نباشند، نسخه ماژول باید ارتقا داده شود. پس‌از تکمیل ارتقا، فرایند انتقال آغاز خواهد شد.
4. پس‌از تکمیل انتقال، وضعیت به «انتقال تکمیل شد» تغییر می‌کند و میاناهای برنامه‌سازی کاربردی ماژول رفع انسداد می‌شوند.
5. اکنون APK می‌تواند حذف نصب شود.

عناصر میانای کاربر انتقال

صفحه‌های زیر توسط ماژول چارچوب برای اهداف آموزش کاربر، هم قبل و هم درطول انتقال نمایش داده می‌شوند:

شکل ۱. اگر Health Connect APK «آگاه از انتقال» نباشد، پیام‌واره‌ای نمایش داده می‌شود که به کاربر دستور می‌دهد APK را به‌روز کند. اگر کاربر به‌روزرسانی را رد کند، واحد به کار خود ادامه می‌دهد و شروع به جمع‌آوری اجازه‌ها و داده‌ها می‌کند.

شکل ۲. اگر ماژول چارچوب برای سازگار شدن با ویژگی به به‌روزرسانی نیاز داشته باشد، پیام‌واره‌ای نمایش داده می‌شود که از کاربر می‌خواهد به‌روزرسانی را انجام دهد و دستگاهش را بازراه‌اندازی کند. اگر کاربر به‌روزرسانی را رد کند، عملکرد واحد ادامه می‌یابد و شروع به جمع‌آوری اجازه‌ها و داده‌ها می‌کند.

شکل ۳. درطول فرایند انتقال، یک نشانگر چرخان به‌همراه نوشتاری که توضیح می‌دهد داده‌ها درحال همگام‌سازی است نمایش داده می‌شود.

داده‌های تکرارزدایی‌شده

اگر ماژول چارچوب شروع به دریافت داده‌ها و اجازه‌ها کرده باشد قبل‌از اینکه هرگونه انتقال یا بازیابی مبتنی بر ابر انجام شده باشد، قوانین زیر اعمال می‌شود.

اجازه‌ها

اگر اجازه‌ها در واحد چارچوب وجود داشته باشد، هرگونه اجازه تکراری که از APK دریافت شده باشد درطول فرایند انتقال نادیده گرفته می‌شود.

داده

درطول انتقال، داده‌های تکراری که از APK منشأ می‌گیرند نادیده گرفته می‌شوند. داده‌های جدیدتر از ماژول در اولویت قرار می‌گیرد.

اگر شناسه سابقه توسط کارخواه ارائه شده باشد، داده‌ها در clientRecordId تکرارزدایی می‌شوند. اگر این‌طور نباشد، فاصله‌های زمانی (startTime و endTime برای سوابق داخلی، و time برای سوابق فوری) به‌همراه نوع داده و نام بسته برنامه به‌عنوان کلید درنظر گرفته می‌شوند.

تغییرات در کیت توسعه نرم‌افزار Jetpack

کیت توسعه نرم‌افزار Jetpack به‌عنوان نقطه ادغام مشترک برای Health Connect APK و میاناهای برنامه‌سازی کاربردی چارچوب Health Connect عمل می‌کند.

سازندگان تجهیزات اصلی می‌توانند ادغام با Jetpack 13 را شروع کنند تا وقتی Jetpack 14 دردسترس قرار گرفت، بتوانید کتابخانه جدید را اختصاص دهید و آن را در Android 14 کامپایل کنید.

نسخه جدیدی از کیت توسعه نرم‌افزار را منتشر خواهیم کرد که از انتقال به 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>

برای پشتیبانی از 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، باید از کنش هدف استفاده کنید که در کیت توسعه نرم‌افزار 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 به‌عنوان بخشی از به‌روزرسانی کیت توسعه نرم‌افزار در آوریل منتشر خواهند شد.

به‌روزرسانی نوع جلسه تمرین

انواع جلسه تمرین زیر دیگر پشتیبانی نخواهند شد و درعوض بعداً به‌عنوان انواع بخش اضافه خواهند شد:

• 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 را دریافت خواهید کرد. این موارد باید به روش‌های زیر (به‌ترتیب اولویت) رسیدگی شوند:

‫۱. همه داده‌ها را از مُهر زمان «آخرین خواندن» یا برای ۳۰ روز گذشته بخوانید و تکرارزدایی کنید

مُهر زمان آخرین باری را که برنامه داده‌ها را از Health Connect خوانده است ذخیره می‌کند. درصورت انقضای توکن، داده‌ها باید از این مقدار یا ۳۰ روز گذشته (هرکدام که حداقل باشد) دوباره خوانده شود و بااستفاده از UUID، داده‌های تکراری نسبت‌به داده‌های قبلی خوانده‌شده حذف شود.

‫۲. خواندن داده‌ها از مُهر زمان «آخرین خواندن»

مُهر زمانی‌ای ایجاد کنید که نشان دهد داده‌ها آخرین‌بار چه زمانی از Health Connect خوانده شده‌اند ، و پس‌از انقضای کد، همه داده‌های بعداز آن مقدار را بخوانید.

‫۳. حذف و خواندن مجدد داده‌های ۳۰ روز گذشته

همه داده‌های خوانده‌شده از Health Connect در ۳۰ روز گذشته را حذف کنید و همه آن داده‌ها را دوباره بخوانید (مثلاً همان‌طور که وقتی برنامه‌ها برای اولین‌بار با Health Connect ادغام می‌شوند انجام می‌شود).

‫۴. هیچ کاری انجام ندهید (یعنی داده‌های ۳۰ روز گذشته را دوباره بخوانید و تکرارزدایی نکنید)

این روش باید به‌عنوان آخرین راهکار استفاده شود، زیرا خطر نمایش داده‌های تکراری را به‌همراه دارد. توسعه‌دهندگان باید گزینه‌های ۱ تا ۳ را کاوش کنند، زیرا UUID-ها باید ازقبل وجود داشته باشند.

آزمایش کردن میاناهای برنامه‌سازی کاربردی Android 14 با کیت توسعه نرم‌افزار Jetpack

کیت توسعه نرم‌افزار Android 14 Jetpack قرار است در ۷ ژوئن ۲۰۲۳، همراه با نسخه Beta 3 از Android 14 منتشر شود. برای اینکه بتوانید از «کیت توسعه نرم‌افزار Jetpack» در Android 14 استفاده کنید، باید کامپایل کردن برنامه‌تان را در Android 14 شروع کنید.

اگر می‌خواهید راه‌حل خود را درمقابل نسخه‌های «پیش‌نمایش توسعه‌دهندگان Android» قبل‌از ۷ ژوئن آزمایش کنید، برای دریافت راهنمایی با «نقطه تماس» Google خود تماس بگیرید.

اگر می‌خواهید راه‌حلتان را درمقابل نسخه Beta 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 ازطریق استفاده از هم‌پوشانی‌های سفارشی، زمینه‌سازی OEM را ارائه می‌دهد.

برای اسناد مربوط به سبک‌بندی OEM، به اسناد «خدمات تلفن همراه Google» در Health Connect مراجعه کنید. ممکن است برای مشاهده صفحه لازم باشد به سیستم Google Developers وارد شوید.