パフォーマンスを計画する

アプリをヘルスコネクトと併用した場合に高いパフォーマンスを発揮できるよう、以下のベスト プラクティス ガイドラインに準拠することをおすすめします。

データを書き込む

アプリは、独自のソースのデータのみをヘルスコネクトに書き込む必要があります。

アプリのデータが別のアプリからインポートされたものである場合、そのデータをヘルスコネクトに書き込む役割はインポート元のアプリが担います。

また、境界外のデータや内部システムエラーなどの書き込み例外を処理するロジックを実装することもおすすめします。バックオフと再試行の戦略は、ジョブ スケジューリング メカニズムに適用できます。ヘルスコネクトへの書き込みが最終的に失敗した場合でも、アプリは必要な処理を引き続き行える状態でなければなりません。診断に役立てるため、必ずエラーをログに記録して報告してください。

データをトラッキングする場合、アプリがデータを書き込む方法に応じて、いくつかの推奨事項があります。

パッシブ トラッキング

これには、受動的なフィットネス管理または健康管理を行うアプリ（たとえば、バックグラウンドで歩数や心拍数を継続的に記録するアプリ）が含まれます。

アプリは以下の方式でヘルスコネクトに定期的にデータを書き込む必要があります。

  • 同期のたびに新しいデータのみを書き込み、前回の同期の後で変更されたデータのみを更新します。
  • 1 回の書き込みリクエストのレコード数を最大 1,000 個にしてリクエストをチャンクします。
  • WorkManager を使用して、定期的なバックグラウンド タスクを少なくとも 15 分の期間にスケジュール設定します。

  • デバイスがアイドル状態でバッテリー残量が十分にある場合にのみタスクを実行するよう制限します。

    val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

アクティブ トラッキング

これには、エクササイズや睡眠などのイベントベースのトラッキングを行うアプリや、栄養などの手動のユーザー入力を行うアプリが含まれます。これらのレコードは、アプリがフォアグラウンドにある場合、または 1 日に数回使用されるまれなイベントの場合に作成されます。

イベント期間全体を通じて、アプリでヘルスコネクトの実行が維持されないようにします。

データは、次の 2 つの方法のいずれかを使って、ヘルスコネクトに書き込む必要があります。

  • イベントの完了後にデータをヘルスコネクトに同期します。たとえば、トラッキング対象のエクササイズ セッションが終了したときにデータを同期します。
  • WorkManager を使用して、1 回限りのタスクのデータを後で同期するようにスケジュール設定します。

サンプルレート

ヘルスコネクトにデータを書き込むときには、適切なサンプルレートを使用してストレージの負荷を軽減します。たとえば、歩数データをどれくらいの頻度で記録する必要があるか、アクティブなワークアウトにリンクされるデータ型（速度など）にはどのようなサンプルレートが必要かなどを検討することが重要です。

すべてのデータ型に同じサンプルレートが必要なわけではありません。歩数データを 1 秒ごとに更新してもあまり意味はありません。60 秒程度の少ない頻度で十分です。一方で、サンプルレートが高いほど、ユーザーは健康とフィットネスのデータをよりきめ細かく把握できます。サンプルレートの頻度は、細かさとパフォーマンスのバランスを取って設定する必要があります。

データを同期する

同期プロセスに影響する要因には、次のものがあります。

トークンの有効期限

未使用の変更トークンは 30 日以内に期限切れになるため、そのような場合に情報が失われることのない同期戦略を採用する必要があります。同期戦略には次のようなアプローチがあります。

  • アプリのデータストアで、ヘルスコネクトの id が付与されている、最近使用されたレコードを検索します。
  • 特定のタイムスタンプで始まるレコードをヘルスコネクトにリクエストし、アプリのデータストアで挿入または更新します。
  • 変更トークンをリクエストし、次回必要なときに使用できるように確保します。

推奨されるチェンジ マネジメント戦略

アプリが無効になった場合や変更トークンが期限切れになった場合に備えて、ロジックへの適用方法に応じて次のマネジメント戦略をおすすめします。

  • すべてのデータを読み取って重複を排除する。これが最も理想的な戦略です。
    • 最後にヘルスコネクトからデータを読み込んだときのタイムスタンプを保存します。
    • トークンの有効期限が切れたときに、最新のタイムスタンプまたは過去 30 日間のすべてのデータを再読み取りする。次に、識別子を使用して、以前に読み取ったデータとの重複を排除する。
    • データの更新にはクライアント ID が必要なため、できる限りクライアント ID を実装する。
  • 前回の読み取りのタイムスタンプ以降のデータのみを読み取る。その結果、変更トークンの有効期限が切れるタイミングでデータの不一致が発生するものの、その期間は数時間から数日の短い期間になります。
    • 最後にヘルスコネクトからデータを読み込んだときのタイムスタンプを保存します。
    • トークンの期限が切れたときに、このタイムスタンプ以降のすべてのデータを読み取ります。
  • データを削除して、過去 30 日間のデータを読み取る。これは最初の統合で行われることと非常に似ています。
    • 過去 30 日間にヘルスコネクトからアプリが読み取ったデータをすべて削除します。
    • 削除後にこのデータをすべて再度読み取ります。
  • 重複を排除することなく過去 30 日間のデータを読み取る。これは最もおすすめしない方法で、ユーザーに重複するデータが表示されることになります。
    • 過去 30 日間にヘルスコネクトからアプリが読み取ったデータをすべて削除します。
    • 重複しているエントリを許可します。

データ型の変更トークン

アプリが複数のデータ型を個別に使用する場合は、データ型ごとに個別の変更トークンを使用します。Changes Sync API で複数のデータ型のリストを使用できるのは、それらのデータ型が一緒に使用される場合、またはいずれも使用されない場合のみです。

フォアグラウンドでの読み取り

アプリがフォアグラウンドにある間のみ、ヘルスコネクトからデータを読み取れます。ヘルスコネクトからデータを同期するときに、ヘルスコネクトへのアクセスが予期せず中断される場合があります。たとえば、ヘルスコネクトから大量のデータを読み取るときの同期途中の中断に対応し、次回アプリが開かれたときに続行する必要があります。

インポートのタイミング

アプリは新規データについて通知されないため、次の 2 つのタイミングで新規データがあるかどうかを確認する必要があります。

  • アプリがフォアグラウンドでアクティブになったときに確認します。この場合は、ライフサイクル イベントを使用します。
  • アプリがフォアグラウンドにある間は定期的に確認します。新しいデータが利用可能になったらユーザーに通知して、画面を更新して変更を反映できるようにします。

レート制限

まれではありますが、ヘルスコネクトがアプリからのリクエストに対してレート制限を行うことがあります。これは、バッテリーとパフォーマンスへの影響を抑えるためです。

  • レート制限によってアプリのリクエストが拒否されないように、ベスト プラクティス ガイドラインに従うことを強くおすすめします。
  • アプリはレート制限に対する耐性を持つ必要があります。たとえば、レート制限によってリクエストが失敗した場合でも、次回の定期タスクでデータをバックグラウンドで書き込めます。

アプリのオンボーディング

多くのアプリには機能の説明やユーザーの同意の確認など、カスタムのオンボーディング フローがあります。ユーザーが初めてアプリを使用したときにヘルスコネクトが起動するオンボーディング アクティビティをエクスポートすることを強くおすすめします。そのためにはマニフェストに次の行を追加します。

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

この機能は Android 14 ではまだ利用できませんが、近日中にリリースされる予定です。

ユーザーがアプリをヘルスコネクトに接続しようとすると、エクスポートされたアクティビティが起動されます。このアクティビティで次のことを行う必要があります。

  • 書き込みまたは読み取り対象のデータに関する説明など、関連するユーザー向け情報を表示します。
  • 必要な場合はユーザーに同意を求めます。
  • ヘルスコネクトへの権限のリクエストを行います。
  • 定期的なワーカーのスケジュール設定など、その他のアプリ固有のロジックを実行します。
  • 完了後、ユーザーがアクティビティを閉じられるようにします。

オンボーディング アクティビティをエクスポートしていないアプリの場合、ユーザーがアプリを接続しようとするとヘルスコネクトが [権限の管理] 画面を表示します。アプリの前提条件として、権限さえ付与されていれば統合が機能する場合には、これで問題ありません。

オンボーディング アクティビティは、複数回起動される場合があります。後でユーザーがアプリの権限を取り消して、再度接続した場合などが該当します。