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

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

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

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

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

طرح مهاجرت

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

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

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

مثال 1 - در حال اجرا (داده های بازه ای)

یک کاربر هر روز رکوردهای 10 ساله دویدن را به مدت 1 ساعت جمع آوری کرده است. این برابر است با:

  • سوابق جلسه تمرین: 365 * 10 * 1
  • مراحل: 365 * 10 * 1
  • کالری: 365 * 10 * 1
  • مجموع = 365 * 10 * 3 (365 * 30) = 10150

با توجه به اینکه 1 تکه معادل 3000 رکورد است، داده های فوق در مجموع حدود 4 تکه است.

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

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

یک کاربر 5 سال داده ضربان قلب (با رکورد ایجاد شده در هر دقیقه) جمع آوری کرده است که در مجموع 2,628,000 رکورد را شامل می شود.

با 3000 رکورد در هر قطعه، داده ها در 876 قطعه توزیع می شوند. با توجه به اینکه وارد کردن 1 قطعه تقریباً یک ثانیه طول می کشد، داده ها در کمتر از 15 دقیقه منتقل می شوند.

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

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

بیایید نگاهی به یک جریان مهاجرت در سطح بالا بیندازیم:

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

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

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

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

به روز رسانی تلفن مورد نیاز است


شکل 2. اگر ماژول فریمورک برای سازگاری با ویژگی ها به به روز رسانی نیاز داشته باشد، یک اعلان نمایش داده می شود که از کاربر می خواهد به روز رسانی را انجام دهد و دستگاه خود را راه اندازی مجدد کند. اگر کاربر به‌روزرسانی را رد کند، ماژول به کار خود ادامه می‌دهد و شروع به جمع‌آوری مجوزها و داده‌ها می‌کند:

به‌روزرسانی APK مورد نیاز است


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

همگام سازی داده ها

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

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

مجوزها

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

داده ها

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

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

تغییرات در Jetpack SDK

Jetpack SDK به عنوان نقطه ادغام مشترک برای Health Connect APK و Health Connect Framework APIها عمل می کند.

OEM ها می توانند شروع به ادغام با Jetpack 13 کنند تا زمانی که Jetpack 14 در دسترس قرار گرفت، بتوانید کتابخانه جدید را اختصاص دهید و آن را در اندروید 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>

برای پشتیبانی از 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 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 به 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 ها باید از قبل وجود داشته باشند.

تست APIهای Android 14 با Jetpack SDK

Android 14 Jetpack SDK قرار است در تاریخ 7 ژوئن 2023 همراه با نسخه بتا 3 اندروید 14 منتشر شود. برای اینکه بتوانید از Android 14 Jetpack SDK استفاده کنید باید کامپایل برنامه خود را در برابر اندروید 14 آغاز کنید.

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

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

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

سفارشی سازی OEM

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

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

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