Memigrasikan Health Connect dari Android 13 (APK) ke Android 14 (framework)

Health Connect akan dikemas dengan Android 14 sebagai lapisan penyimpanan data umum untuk data kesehatan konsumen yang dilindungi oleh izin terperinci dan dapat diakses sebagai aplikasi sistem Android (dalam dokumen ini disebut sebagai 'framework' ).

Developer harus mempertimbangkan APK Health Connect (Android 13) sebagai lapisan kompatibilitas mundur untuk model framework. Model framework akan mempertahankan paritas fitur 100% dengan APK sebelumnya.

Selama transisi dari Android 13 ke 14, pengalaman pengguna harus tetap lancar dan intuitif.

Dokumen ini menguraikan rencana migrasi, memberikan beberapa contoh skenario migrasi, dan mencantumkan perubahan pada Jetpack SDK yang memfasilitasi akses ke Health Connect API.

Rencana migrasi

  1. Setelah Android 14 dirilis, Google akan beralih menyediakan Health Connect sebagai aplikasi sistem Android.
  2. Kemudian, data akan diisi ulang dari APK setelah paritas fitur tercapai.
  3. Semua titik entri akan menargetkan UI aplikasi sistem.
  4. Migrasi data akan dimulai. Saat migrasi berlangsung, API modul akan ditangguhkan dengan status 'Migrasi dalam Proses'. Status ini juga akan terlihat dalam UI Health Connect.
  5. Setelah migrasi selesai, APK dapat di-uninstal.

Contoh skenario migrasi

Berikut beberapa contoh skenario yang menjelaskan proses migrasi untuk jenis data interval dan series:

Contoh 1 - Berjalan (data interval)

Seorang pengguna telah mengumpulkan 10 tahun kumpulan data berjalan selama 1 jam setiap hari. Ini setara dengan:

  • Kumpulan Data Sesi Latihan: 365 * 10 * 1
  • Langkah: 365 * 10 * 1
  • Kalori: 365 * 10 * 1
  • Total = 365 * 10 * 3 (365 * 30) = 10.150

Mengingat bahwa 1 bagian setara dengan 3.000 kumpulan data, maka data di atas berjumlah sekitar 4 bagian.

Pengujian internal kami telah mengonfirmasi bahwa bagian umum memerlukan waktu penyisipan sekitar satu detik sehingga data di atas akan dimigrasikan dalam waktu sekitar 4 detik.

Contoh 2 - Detak jantung (data seri)

Seorang pengguna telah mengumpulkan 5 tahun data detak jantung (dengan kumpulan data yang dibuat setiap menit) dengan total 2.628.000 kumpulan data.

Data ini akan didistribusikan di 876 bagian karena setiap bagian setara dengan 3.000 kumpulan data. Mengingat bahwa satu bagian membutuhkan waktu penyisipan sekitar satu detik, maka data akan dimigrasikan dalam waktu kurang dari 15 menit.

Alur migrasi yang diusulkan

Kami telah memutuskan untuk memilih migrasi instan. Dalam praktiknya, memilih migrasi instan berarti APK akan langsung tidak aktif setelah perangkat diupgrade ke Android 14, dengan sangat sedikit intervensi dari pengguna.

Mari kita lihat alur migrasi tingkat tinggi:

  1. Pengguna mengupgrade perangkat mereka ke Android 14.
  2. Jetpack 14 mengarahkan pengguna ke API modul, dan akan memblokirnya selama migrasi berlangsung.
  3. Proses migrasi dimulai saat versi modul kompatibel dengan fitur APK, yaitu versi modul berisi kumpulan fitur yang sama, atau lainnya. Setelah proses migrasi dimulai, APK akan memigrasikan izin dan data.
    1. Jika kedua versi tidak kompatibel dengan fitur, versi modul harus diupgrade. Setelah upgrade selesai, proses migrasi akan dimulai.
  4. Setelah migrasi selesai, status diubah menjadi 'Migrasi Selesai', dan API modul berhenti diblokir.
  5. Kini, APK dapat di-uninstal.

Elemen UI migrasi

Layar berikut ditampilkan oleh modul framework untuk tujuan pendidikan pengguna, sebelum dan selama migrasi:

Gambar 1. Jika APK Health Connect tidak 'mengetahui migrasi', perintah yang meminta pengguna mengupdate APK akan muncul. Jika pengguna menolak update, modul akan terus berfungsi serta mulai mengumpulkan izin dan data:

Update ponsel diperlukan


Gambar 2. Jika modul framework memerlukan update agar kompatibel dengan fitur, perintah yang meminta pengguna untuk melakukan update dan memulai ulang perangkat akan muncul. Jika pengguna menolak update, modul akan terus berfungsi serta mulai mengumpulkan izin dan data:

Update APK diperlukan


Gambar 3. Indikator lingkaran berputar ditampilkan selama proses migrasi, dengan teks yang menjelaskan bahwa data sedang disinkronkan:

Sinkronisasi Data

Penghapusan duplikasi data

Jika modul framework mulai memperoleh data dan izin sebelum migrasi atau pemulihan berbasis cloud berlangsung, aturan berikut akan berlaku.

Izin

Jika izin ada dalam modul framework, izin duplikat yang diperoleh dari APK akan diabaikan selama proses migrasi.

Data

Selama migrasi, data duplikat yang berasal dari APK akan diabaikan. Data yang lebih baru dari modul ini lebih diutamakan.

Duplikat data akan dihapus di clientRecordId jika ID kumpulan data disediakan oleh klien. Jika tidak, interval waktu (startTime dan endTime untuk kumpulan data internal, dan time untuk kumpulan data instan) diperlakukan sebagai kunci, beserta jenis data dan nama paket aplikasi ini.

Perubahan di Jetpack SDK

Jetpack SDK berfungsi sebagai titik integrasi umum untuk APK Health Connect dan API framework Health Connect.

OEM dapat mulai berintegrasi dengan Jetpack 13 sehingga saat Jetpack 14 tersedia, Anda dapat menyesuaikan library baru dan mengompilasinya dalam Android 14.

Kami akan merilis versi baru SDK yang mendukung transisi ke Android 14. Anda perlu membuat beberapa perubahan pada integrasi yang ada untuk memastikan transisi berjalan dengan lancar.

Pernyataan izin

Di Android 13, Anda mendeklarasikan izin menggunakan format izin kustom dalam file resource yang ditautkan ke manifes:

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

Untuk mendukung Android 14, developer harus beralih ke format izin standar:

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

Membuka Health Connect

Sebagian besar aplikasi pihak ketiga menampilkan tombol untuk membuka aplikasi Health Connect, seperti tombol 'Kelola Akses' di Fitbit.

Di Android 13, Anda dapat membuka aplikasi Health Connect menggunakan nama paket, atau melalui tindakan androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

Di Android 14, Anda perlu menggunakan tindakan intent, yang ditentukan di Jetpack SDK, yang memiliki nilai berbeda berdasarkan versi Android yang ditindaklanjuti:

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

Mendapatkan klien Health Connect

Kami telah membuat satu API bernama sdkStatus yang tersedia di Jetpack 11 untuk mengganti dua API lain yang tidak digunakan lagi - IsSdkSupported() dan isProviderAvailable().

Perubahan API catatan sesi

Empat subjenis ExerciseSession telah dihapus sebagai bagian dari rilis alpha10:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Seperti halnya ExerciseSessionRecord, SleepStage akan menjadi subjenis SleepSession.

Baik subjenis ExerciseSessionRecord maupun perubahan SleepSession akan dirilis sebagai bagian dari update SDK untuk April.

Pembaruan jenis sesi latihan

Jenis sesi olahraga di bawah ini tidak akan didukung lagi, dan akan ditambahkan sebagai jenis segmen di lain waktu:

  • 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

Jenis penggantian:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Penanganan log perubahan

Log perubahan tidak akan dimigrasikan sebagai bagian dari peralihan dari APK ke Android 14.

Setelah migrasi selesai, Anda akan mulai menerima pengecualian TOKEN_EXPIRED atau TOKEN_INVALID. Pengecualian ini harus ditangani dengan cara berikut (sesuai urutan preferensi):

1. Membaca dan menghapus semua data sejak stempel waktu 'terakhir dibaca', atau selama 30 hari terakhir

Menyimpan stempel waktu saat aplikasi terakhir kali membaca data dari Health Connect. Saat masa berlaku token habis, data harus dibaca ulang dari nilai ini, atau 30 hari sebelumnya (mana pun yang sama dengan nilai minimumnya), dan menghapus duplikatnya dari data yang sebelumnya dibaca menggunakan UUID.

2. Membaca data sejak stempel waktu 'terakhir dibaca'

Tetapkan stempel waktu yang menunjukkan kapan data terakhir dibaca dari Health Connect, dan setelah token berakhir, baca semua data setelah nilai tersebut.

3. Menghapus dan membaca ulang data selama 30 hari terakhir

Hapus semua data yang dibaca dari Health Connect dari 30 hari sebelumnya, lalu baca lagi semua data tersebut (misalnya seperti yang dilakukan saat aplikasi pertama kali berintegrasi dengan Health Connect).

4. Tidak melakukan apa pun (yaitu membaca ulang data selama 30 hari terakhir dan tidak menghapus duplikat)

Tindakan ini harus digunakan sebagai upaya terakhir, dengan kemungkinan risiko menampilkan data duplikat. Sebagai gantinya, developer sebaiknya mempelajari opsi 1-3 karena UUID harus diterapkan.

Menguji API Android 14 dengan Jetpack SDK

Jetpack SDK Android 14 akan dirilis pada 7 Juni 2023, bersama dengan rilis Beta 3 Android 14. Anda harus mulai mengompilasi aplikasi di Android 14 agar dapat menggunakan Jetpack SDK Android 14.

Jika ingin menguji solusi Anda di build Pratinjau Developer Android sebelum 7 Juni, hubungi Google POC Anda untuk mendapatkan bantuan.

Jika ingin menguji solusi di rilis Beta 3, Anda harus melakukan perubahan berikut pada APK:

  1. Setel compileSDKPreview = UpsideDownCake.
  2. Update manifes agar menyertakan intent untuk 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>

Penyesuaian OEM

Di Android 14, kontrol privasi & pengelolaan data Health Connect ada di Setelan Sistem.

Untuk membuat tampilan izin dan pengelolaan data terlihat seperti bagian dari perangkat, Health Connect menawarkan tema OEM melalui penggunaan overlay kustom.

Untuk dokumentasi tentang gaya OEM, baca dokumentasi Layanan Seluler Google Health Connect.