ヘルスコネクトを Android 13（APK）から Android 14（フレームワーク）に移行する

ヘルスコネクトは、消費者の健康データ用の一般的なデータ ストレージ レイヤとして Android 14 とともにパッケージ化されます。また、きめ細かい権限で保護され、さらに Android システムアプリ（このドキュメントでは「フレームワーク モジュール」と呼びます）としてアクセスできるようになります。

デベロッパーは、ヘルスコネクト APK（Android 13）をフレームワーク モデルの下位互換性レイヤと見なす必要があります。フレームワーク モデルは、従来の APK と 100% 同等の機能を維持します。

Android 13 から 14 に移行するにあたり、ユーザー エクスペリエンスを可能な限りスムーズで直感的なものにすることが不可欠です。

このドキュメントでは、移行計画の概要、移行シナリオの例について説明します。また、Jetpack SDK はヘルスコネクト API へのアクセスが簡単になるよう変更されていますが、これらの変更点についても説明します。

移行プラン

  1. Android 14 のリリースに伴い、ヘルスコネクトは Android システムアプリとして提供されることになります。
  2. 同等の機能が実現されると、データが APK からバックフィルされます。
  3. すべてのエントリ ポイントがシステムアプリの UI をターゲットにします。
  4. データの移行が開始します。移行の進行中は、モジュール API が停止し、ステータスが「移行中」になります。このステータスはヘルスコネクトの UI にも表示されます。
  5. 移行が完了したら、APK をアンインストールできます。

移行シナリオの例

interval と series の両方のデータ型の移行プロセスを説明するシナリオ例を次に示します。

例 1 - 実行中（間隔データ）

あるユーザーが、10 年間、実行中のデータを毎日 1 時間ずつ収集しています。レコード数は次のようになります。

  • エクササイズ セッションのレコード: 365 * 10 * 1
  • 歩数: 365 * 10 * 1
  • 消費カロリー: 365 * 10 * 1
  • 合計 = 365 * 10 * 3 (365 * 30) = 10,150

1 チャンクは 3,000 レコードに相当するため、上記のデータの合計は約 4 チャンクとなります。

Google の内部テストにより、一般的なチャンクの挿入に約 1 秒かかることが確認されています。つまり、上記のデータは約 4 秒で移行されることになります。

例 2 - 心拍数（系列データ）

あるユーザーが 5 年間の心拍数データを収集し（レコードは 1 分ごとに作成されています）、レコード数の合計は 2,628,000 件に達しています。

チャンクあたりのレコード数は 3,000 件なので、データは 876 のチャンクに分散されます。1 つのチャンクの挿入にかかる時間は約 1 秒なので、データは 15 分以内に移行されます。

提案された移行フロー

新しく即時移行が導入されます。具体的には、デバイスが Android 14 にアップグレードされるとすぐに APK は無効になります。そのためのユーザー操作は最小限に抑えられます。

大まかな移行フローを見てみましょう。

  1. ユーザーがデバイスを Android 14 にアップグレードします。
  2. Jetpack 14 はユーザーをモジュールの API に誘導し、移行の進行中はこれらの API をブロックします。
  3. 移行プロセスは、モジュール バージョンの機能が APK と互換性がある場合（つまり、モジュール バージョンに同等以上の機能セットが含まれている場合）に開始されます。移行プロセスが開始されると、APK は権限とデータを移行します。
    1. 両方のバージョンの機能に互換性がない場合は、モジュール バージョンをアップグレードする必要があります。アップグレードが完了すると、移行処理が開始されます。
  4. 移行が完了すると、状態は「移行完了」に変更され、モジュールの API のブロックが解除されます。
  5. これで APK をアンインストールできるようになりました。

移行 UI 要素

移行前と移行中の両方で、ユーザー教育を目的として、フレームワーク モジュールに次の画面が表示されます。

図 1. ヘルスコネクト APK が「移行対応」でない場合、APK を更新するよう促すプロンプトがユーザーに表示されます。ユーザーが更新を拒否した場合も、モジュールは引き続き機能し、権限とデータの蓄積が開始されます。

スマートフォンの更新が必要


図 2. フレームワーク モジュールの機能の互換性を維持するために更新が必要な場合は、更新を実行してデバイスを再起動するようにユーザーに求めるプロンプトが表示されます。ユーザーが更新を拒否した場合も、モジュールは引き続き機能し、権限とデータの蓄積が開始されます。

APK の更新が必要


図 3. 移行プロセス中は、データが同期されていることを示すテキストとともにスピナーが表示されます。

データの同期

重複が排除されたデータ

移行またはクラウドベースの復元が行われる前にフレームワーク モジュールによるデータと権限の取得が開始されている場合、次の規則が適用されます。

権限

フレームワーク モジュールに権限が存在する場合、APK から取得した重複する権限は、移行プロセス中に無視されます。

データ

移行中、APK から取得した重複するデータは無視されます。モジュールからの新しいデータが優先されます。

レコード ID がクライアントから提供されている場合、データは clientRecordId で重複排除されます。そうでない場合、時間間隔（内部レコードの場合は startTime と endTime、インスタント レコードの場合は time）が、データ型とパッケージ名とともにキーとして扱われます。

Jetpack SDK の変更点

Jetpack SDK は、ヘルスコネクト APK とヘルスコネクト フレームワーク API の両方に共通の統合ポイントとして機能します。

OEM は Jetpack 13 との統合を開始できるため、Jetpack 14 が利用可能になったら、新しいライブラリを使用して Android 14 内でコンパイルできるようになります。

Android 14 への移行に対応した新しいバージョンの SDK がリリースされます。移行がスムーズになるように、既存の統合に変更を加える必要があります。

権限の申告

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>

ヘルスコネクトを開く

ほとんどのサードパーティ アプリには、ヘルスコネクト アプリを開くボタンがあります（例: Fitbit の [アクセスを管理する] ボタン）。

Android 13 では、ヘルスコネクト アプリを開くには、パッケージ名を使用するか、androidx.health.ACTION_HEALTH_CONNECT_SETTINGS アクションを使用します。

Android 14 では、Jetpack SDK で指定されたインテント アクションを使用する必要があります。使用している Android のバージョンによって値は異なります。

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

ヘルスコネクト クライアントを取得する

サポートが終了した他の 2 つの API（IsSdkSupported() と isProviderAvailable()）に代わるものとして、Jetpack 11 で利用可能な sdkStatus という単一の API が作成されました。

セッション記録 API の変更

alpha10 リリースの一部として、次の 4 つの ExerciseSession サブタイプが削除されました。

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

ExerciseSessionRecord と同様に、SleepStage は SleepSession のサブタイプになります。

ExerciseSessionRecord サブタイプと SleepSession の変更は、4 月の 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 日間のすべてのデータを読み取り重複を排除する

アプリがヘルスコネクトから最後にデータを読み込んだときのタイムスタンプを保存します。トークンが期限切れになった場合、この値、または過去 30 日間のいずれか小さい方からデータを再度読み込み、UUID を使用して以前に読み込まれたデータとの重複を排除する必要があります。

2. 「最終読み込み日時」タイムスタンプ以降のデータを読み込む

ヘルスコネクトからデータが最後に読み込まれた日時を示すタイムスタンプを設定し、トークンの有効期限が切れたらその値の後のデータをすべて読み取ります。

3. 過去 30 日間のデータを削除して再度読み込む

ヘルスコネクトから過去 30 日間に読み込まれたデータをすべて削除し、そのデータをすべて再度読み取る（アプリが初めてヘルスコネクトと統合されたときなどと同様）

4. 何もしない（過去 30 日間のデータを再度読み取り、重複は排除しない）

これはあくまで最後の手段として使用します。この場合、データが重複して表示される可能性があります。デベロッパーは、UUID がすでに存在することを前提として、方法 1～3 を検討する必要があります。

Jetpack SDK を使用した Android 14 API のテスト

Android 14 の Jetpack SDK は、Android 14 のベータ版 3 リリースとともに 2023 年 6 月 7 日にリリースされる予定です。Android 14 Jetpack SDK を使用するには、Android 14 に対してアプリのコンパイルを開始する必要があります。

6 月 7 日より前に Android デベロッパー プレビュー ビルドに対してソリューションをテストする場合は、Google の POC にお問い合わせください。

ソリューションをベータ版 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>

OEM のカスタマイズ

Android 14 では、ヘルスコネクトのプライバシーとデータを管理するためのコントロールは、システム設定内にあります。

ヘルスコネクトでは、データ管理画面と権限画面をデバイスの一部のようなデザインで使用できるように、カスタム オーバーレイを使用して OEM のテーマ設定を行うことができます。

OEM のスタイル設定については、ヘルスコネクトの Google モバイル サービスのドキュメントをご覧ください。