メタデータの要件

このガイドは、ヘルスコネクトのバージョン 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 つの記録方法のいずれかを指定する必要があります。

次に例を示します。

 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 値は、ヘルスコネクトの新しいバージョンでのみ使用できます。拡張デバイスタイプ機能が利用できない場合、これらのタイプは 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 部分のみを入力します。商品 ID 属性（シリアル番号やバッチ番号など）は含めないでください。

サンプルコード

注: UDI は、Device インスタンスの作成時に設定できます。

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 オープンソース プロジェクトをご覧ください。

テストデータ

Testing Library と 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 で提供されているファクトリ メソッド（Metadata.manualEntry() や Metadata.activelyRecorded(device = Device(...)) など）のいずれかを使用します。
   • デバイスによって記録されたデータの場合、デバイスタイプ（Device.TYPE_WATCH や Device.TYPE_PHONE など）を指定する必要があります。

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