メタデータの要件

このガイドは、ヘルスコネクトのバージョン 1.2.0-alpha05 以降に対応しています。

リリース 1.1.0-alpha12 以降にアップグレードするデベロッパー向けに、ヘルスコネクトのメタデータが変更されています。

ライブラリ情報

Google Maven Android gradle プラグインのアーティファクト ID は、アップグレードが必要なヘルスコネクト ライブラリを識別します。ヘルスコネクト SDK の依存関係をモジュール レベルの build.gradle ファイルに追加します。

dependencies {
  implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}

メタデータの変更

バージョン 1.1.0-alpha12 以降の ヘルスコネクト Jetpack SDK に、有用な追加メタデータがエコシステムに存在することを確認するための 2 つのメタデータ変更が導入されました。metadata が Record コンストラクタに含まれていない場合、コンストラクタの内部エラーが表示されることがあります。

記録方法を指定する

Record() 型のオブジェクトをインスタンス化するたびに、メタデータの詳細を指定する必要があります。

ヘルスコネクトにデータを書き込む場合は、対応するファクトリー メソッドのいずれかを使用して Metadata をインスタンス化し、4 つの記録方法のうちの 1 つを指定する必要があります。

次に例を示します。

 StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    count = 10
)
HealthConnectManager.kt

デバイスの種類

自動的に記録されるデータとアクティブに記録されるデータについては、すべてデバイスタイプを指定する必要があります。詳しくは、Jetpack のドキュメントの Device クラスをご覧ください。現在のデバイスタイプは次のとおりです。

一部の Device.type 値は、Health Connect の新しいバージョンでのみ使用できます。拡張デバイスタイプ機能が利用できない場合、これらのタイプは Device.TYPE_UNKNOWN として扱われます。

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_EXTENDED_DEVICE_TYPES
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

次に例を示します。

 val WATCH_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel Watch",
    type = Device.TYPE_WATCH
)

// Phone
 val PHONE_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel 8",
    type = Device.TYPE_PHONE
)

// Ring
 val RING_DEVICE = Device(
    manufacturer = "Oura",
    model = "Ring Gen3",
    type = Device.TYPE_RING
)

// Scale
 val SCALE_DEVICE = Device(
    manufacturer = "Withings",
    model = "Body Comp",
    type = Device.TYPE_SCALE
)
HealthConnectManager.kt

医療機器の固有識別子（UDI）

Android 17（API レベル 37.1）または U 拡張機能 23 以降のヘルスコネクトでは、Device クラスに固有デバイス ID（UDI）のサポートが含まれています。医療機器の登録済み UDI モデルの詳細を記録と関連付けることで、ダウンストリーム アプリケーション（遠隔医療プラットフォームや臨床ポータルなど）で臨床グレードの測定値を特定し、一般的な消費者向けウェアラブル データと区別できるようになります。

権限を宣言する

UDI の詳細をヘルスコネクトに書き込むには、アプリの AndroidManifest.xml ファイルで WRITE_DEVICE_UDI 権限を宣言する必要があります。

<uses-permission android:name="android.permission.health.WRITE_DEVICE_UDI" />

WRITE_DEVICE_UDI は標準の権限です。マニフェストで宣言する必要がありますが、実行時にユーザーにリクエストする必要はありません。インストール時にアプリに自動的に付与されます。

機器識別子（DI）部分のみを記入する

完全な UDI には次の 2 つの部分が含まれます。

• 機器識別子（UDI-DI）: 発行機関（GS1 など）によって特定のデバイスモデルに割り当てられる、世界的に認められた識別子。
• 製造識別子（UDI-PI）: シリアル番号、バッチ番号、製造日、有効期限など、ユニット固有の属性。

ユーザーのプライバシーを保護するため、ヘルスコネクトではコードの UDI-DI 部分のみを入力してください。製造識別子属性（シリアル番号やバッチ番号など）は含めないでください。

サンプルコード

注: Device インスタンスを構築するときに UDI を設定できます。

val device = Device(
    type = Device.TYPE_CONSUMER_MEDICAL_DEVICE,
    manufacturer = "Omron",
    model = "HEM-7121",
    udi = "04015674011832" // Device Identifier (UDI-DI) portion only
)

val device = Device.Builder()
    .setType(Device.DEVICE_TYPE_CONSUMER_MEDICAL_DEVICE)
    .setManufacturer("Omron")
    .setModel("HEM-7121")
    .setUdi("04015674011832") // Device Identifier (UDI-DI) portion only
    .build()

WRITE_DEVICE_UDI 権限を宣言せずに UDI を含むデータを書き込むと、ヘルスコネクトは書き込み時に SecurityException をスローします。

UDI を使用してデバイスの承認を確認する

ヘルスコネクトはトランスポート層として機能し、UDI の信頼性や登録ステータスを検証しません。

データ閲覧者にとって、UDI の存在は、データが登録済みの医療機器から発信されたことを示します。リーディング アプリは、FDA の Global Unique Device Identification Database（GUDID）や EU の EUDAMED などの規制データベースにクエリを実行して、デバイスの分類、規制上の承認ステータス（クラス I、II、III など）、特定の使用目的を確認する必要があります。

スニペットを更新しました

新しいメタデータ要件に準拠するために新しいスニペットが必要な箇所では、ヘルスコネクト ガイドが更新されています。例については、データの書き込みページをご覧ください。

新しいメタデータ メソッド

メタデータを直接インスタンス化できなくなったため、ファクトリ メソッドのいずれかを使用してメタデータの新しいインスタンスを取得します。ファクトリー メソッドは、デバイスまたはセンサーを使用してデータを記録したときにデバイス情報が提供されたことを確認します。手動で入力したデータの場合、デバイス情報の提供は引き続き任意です。各関数には 3 つのシグネチャ バリアントがあります。

• activelyRecorded

  • fun activelyRecorded(device: Device): Metadata.
  • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun activelyRecordedWithId(id: String, device: Device): Metadata

• autoRecorded

  • fun autoRecorded(device: Device): Metadata
  • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun autoRecordedWithId(id: String, device: Device): Metadata

• manualEntry

  • fun manualEntry(device: Device? = null): Metadata
  • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun manualEntryWithId(id: String, device: Device? = null): Metadata

• unknownRecordingMethod

  • fun unknownRecordingMethod(device: Device? = null): Metadata
  • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata

詳しくは、Android オープンソース プロジェクトをご覧ください。

テストデータ

テスト ライブラリと MetadataTestHelper を使用して、想定されるメタデータ値をモックします。

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

これは、レコードの挿入中にこれらの値を自動的に入力するヘルスコネクトの実装の動作をシミュレートします。

テスト ライブラリの場合は、このヘルスコネクト SDK の依存関係をモジュール レベルの build.gradle ファイルに追加する必要があります。

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

ライブラリをアップグレードする

主な手順は次のとおりです。

1. ライブラリを 1.1.0-alpha12 にアップグレードします。

2. ライブラリをビルドする際に、新しいメタデータが必要な場所でコンパイル エラーがスローされます。これらのエラーを解決して移行を完了するには、次の変更が行われていることを確認します。

   • Record を構築する際は、記録方法を必ず指定する必要があります。これは、Metadata で提供される Factory メソッド（Metadata.manualEntry() や Metadata.activelyRecorded(device = Device(...)) など）のいずれかを使用して行われます。
   • デバイスで記録されたデータについては、Device.TYPE_WATCH や Device.TYPE_PHONE などのデバイスタイプを指定する必要があります。

3. アプリが拡張デバイスタイプを書き込む場合は、FEATURE_EXTENTED_DEVICE_TYPES の背後にゲートして、その機能が利用できないデバイスで予期しない TYPE_UNKNOWN が発生しないようにします。