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

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

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

در طول گذار از اندروید ۱۳ به ۱۴، بسیار مهم است که تجربه کاربری تا حد امکان روان و کاربرپسند باقی بماند.

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

طرح مهاجرت

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

سناریوهای مهاجرت نمونه

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

مثال ۱ - اجرا (داده‌های بازه)

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

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

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

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

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

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

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

جریان مهاجرت پیشنهادی

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

جریان مهاجرت سطح بالا به شرح زیر است:

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

عناصر رابط کاربری مهاجرت

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

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

شکل به‌روزرسانی تلفن مورد نیاز
شکل ۱ : درخواست به‌روزرسانی APK برنامه Health Connect.

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

شکل مورد نیاز برای به‌روزرسانی APK
شکل ۲ : درخواست به‌روزرسانی ماژول چارچوب.

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

شکل همگام‌سازی داده‌ها
شکل ۳ : انتقال داده‌ها در حال انجام است.

داده‌های حذف‌شده

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

مجوزها

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

داده‌ها

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

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

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

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

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

ما نسخه جدیدی از SDK را منتشر خواهیم کرد که از انتقال به اندروید ۱۴ پشتیبانی می‌کند. برای اطمینان از انتقال روان، باید تغییراتی در یکپارچه‌سازی موجود خود ایجاد کنید.

اعلامیه مجوز

در اندروید ۱۳، شما مجوزها را با استفاده از یک قالب مجوز سفارشی، در یک فایل منبع که به مانیفست لینک شده است، اعلام می‌کنید:

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

برای پشتیبانی از اندروید ۱۴، توسعه‌دهندگان باید به فرمت استاندارد مجوزها روی بیاورند:

#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 را باز می‌کند، مانند دکمه «مدیریت دسترسی» در Fitbit.

در اندروید ۱۳، یا با استفاده از نام بسته یا از طریق اکشن androidx.health.ACTION_HEALTH_CONNECT_SETTINGS ، برنامه Health Connect را باز می‌کنید.

در اندروید ۱۴، باید از یک اکشن intent که در Jetpack SDK مشخص شده است استفاده کنید که بسته به نسخه اندروید، مقادیر متفاوتی دارد:

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

دریافت کلاینت Health Connect

ما یک API واحد به نام sdkStatus ایجاد کرده‌ایم که در Jetpack 11 موجود است تا جایگزین دو API منسوخ‌شده‌ی دیگر - IsSdkSupported() و isProviderAvailable() شود.

تغییرات 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 به اندروید ۱۴ منتقل نخواهد شد.

پس از اتمام مهاجرت، با خطاهای TOKEN_EXPIRED یا TOKEN_INVALID مواجه خواهید شد. این خطاها باید به روش‌های زیر (به ترتیب اولویت) مدیریت شوند:

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

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

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

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

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

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

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

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

تست API های اندروید ۱۴ با Jetpack SDK

قرار است کیت توسعه نرم‌افزاری اندروید ۱۴ جت‌پک در ۷ ژوئن ۲۰۲۳، همراه با انتشار بتا ۳ اندروید ۱۴، منتشر شود. برای اینکه بتوانید از کیت توسعه نرم‌افزاری اندروید ۱۴ جت‌پک استفاده کنید، باید کامپایل برنامه خود را برای اندروید ۱۴ آغاز کنید.

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

اگر می‌خواهید راه‌حل خود را در برابر نسخه بتا ۳ آزمایش کنید، باید تغییرات زیر را در APK خود اعمال کنید:

  1. تنظیم compileSDKPreview = UpsideDownCake .
  2. مانیفست را به‌روزرسانی کنید تا یک intent برای اندروید ۱۴ اضافه شود: 
# 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>

سفارشی سازی OEM

در اندروید ۱۴، کنترل‌های حریم خصوصی و مدیریت داده‌ها در Health Connect در تنظیمات سیستم قرار دارند.

برای اینکه صفحات مدیریت داده‌ها و مجوزها مانند بخشی از دستگاه به نظر برسند و حس شوند، Health Connect با استفاده از پوشش‌های سفارشی، تم‌های OEM را ارائه می‌دهد.

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