Anforderungen an Metadaten

Diese Anleitung ist mit Health Connect-Version 1.2.0-alpha05 und höher kompatibel.

Es gibt Änderungen an den Metadaten in Health Connect für Entwickler, die auf Version 1.1.0-alpha12 oder höher aktualisieren.

Bibliotheksinformationen

Die Artefakt-ID des Google Maven Android-Gradle-Plug-ins gibt die Health Connect-Bibliothek an, auf die Sie aktualisieren müssen. Fügen Sie diese Health Connect SDK-Abhängigkeit der Datei „build.gradle“ auf Modulebene hinzu:

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

Metadatenänderungen

In Version 1.1.0-alpha12 des Health Connect Jetpack SDK wurden zwei Änderungen an den Metadaten eingeführt, um zu prüfen, ob zusätzliche nützliche Metadaten im Ökosystem vorhanden sind. Wenn metadata nicht in Ihrem Record-Konstruktor enthalten ist, wird möglicherweise der Fehler Constructor internal angezeigt.

Aufzeichnungsmethode angeben

Sie müssen Metadatendetails angeben, wenn ein Objekt vom Typ „Record()“ instanziiert wird.

Wenn Sie Daten in Health Connect schreiben, müssen Sie eine von vier Aufzeichnungsmethoden angeben. Verwenden Sie dazu eine der entsprechenden Factory-Methoden, um Metadata zu instanziieren:

Beispiel:

 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

Gerätetyp

Sie müssen für alle automatisch und aktiv aufgezeichneten Daten einen Gerätetyp angeben. Weitere Informationen finden Sie in der Device-Klasse in der Jetpack-Dokumentation. Derzeit sind folgende Gerätetypen verfügbar:

Einige Device.type-Werte sind nur in neueren Versionen von Health Connect verfügbar. Wenn die Funktion für erweiterte Gerätetypen nicht verfügbar ist, werden diese Typen als Device.TYPE_UNKNOWN behandelt.

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

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

Beispiel:

 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

Eindeutige Gerätekennung (Unique Device Identifier, UDI)

Für Health Connect unter Android 17 (API-Level 37.1) oder U-Erweiterung 23 oder höher bietet die Klasse Device Unterstützung für die eindeutige Geräte-ID (Unique Device Identifier, UDI). Wenn Sie die registrierten UDI-Modelldetails eines Medizinprodukts mit Ihren schriftlichen Aufzeichnungen verknüpfen, können nachgelagerte Anwendungen (z. B. Telemedizinplattformen oder klinische Portale) Messwerte in klinischer Qualität erkennen und sie von allgemeinen Daten von Wearables für Verbraucher unterscheiden.

Berechtigung deklarieren

Wenn Sie UDI-Details in Health Connect schreiben möchten, müssen Sie die Berechtigung WRITE_DEVICE_UDI in der Datei AndroidManifest.xml Ihrer App deklarieren:

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

WRITE_DEVICE_UDI ist eine normale Berechtigung. Sie müssen sie in Ihrem Manifest deklarieren, aber nicht zur Laufzeit vom Nutzer anfordern. Sie wird Ihrer App bei der Installation automatisch gewährt.

Nur den DI-Teil (Device Identifier) schreiben

Eine vollständige UDI besteht aus zwei Teilen:

• Geräte-ID (UDI-DI): Eine weltweit anerkannte Kennung, die einem bestimmten Gerätemodell von einer ausstellenden Stelle (z. B. GS1) zugewiesen wird.
• Produktionskennung (UDI-PI): Einheitsspezifische Attribute wie Seriennummern, Chargennummern, Herstellungsdaten oder Ablaufdaten.

Zum Schutz der Nutzerdaten darf nur der UDI-DI-Teil des Codes in Health Connect angegeben werden. Geben Sie keine Attribute für Produktionskennungen wie Seriennummern oder Chargennummern an.

Codebeispiel

Hinweis:Sie können die UDI beim Erstellen einer Device-Instanz festlegen.

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()

Wenn Sie Daten mit einer eindeutigen Gerätekennung schreiben, ohne die Berechtigung WRITE_DEVICE_UDI zu deklarieren, löst Health Connect zur Schreibzeit eine SecurityException aus.

UDI zur Überprüfung der Gerätefreigabe verwenden

Health Connect dient als Transportschicht und validiert nicht die Authentizität oder den Registrierungsstatus der UDI.

Für Datenleser weist das Vorhandensein einer UDI darauf hin, dass die Daten von einem registrierten Medizinprodukt stammen. Lese-Apps sollten behördliche Datenbanken wie die Global Unique Device Identification Database (GUDID) der FDA oder EUDAMED der EU abfragen, um Geräteklassifizierungen, den Status der behördlichen Genehmigung (z. B. Klasse I, II oder III) oder die spezifische Zweckbestimmung zu überprüfen.

Snippets aktualisiert

Health Connect-Anleitungen wurden aktualisiert, wenn neue Snippets erforderlich sind, um die neuen Metadatenanforderungen zu erfüllen. Einige Beispiele finden Sie auf der Seite Daten schreiben.

Neue Metadatenmethoden

Metadaten können nicht mehr direkt instanziiert werden. Verwenden Sie daher eine der Factory-Methoden, um eine neue Instanz von Metadaten zu erhalten. Die Factory-Methoden prüfen, ob Geräteinformationen angegeben werden, wenn ein Gerät oder Sensor zum Aufzeichnen der Daten verwendet wurde. Bei manuell eingegebenen Daten ist die Angabe von Geräteinformationen weiterhin optional. Jede Funktion hat drei Signaturvarianten:

• 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

Weitere Informationen finden Sie im Open-Source-Project für Android.

Testdaten

Verwenden Sie die Testbibliothek und MetadataTestHelper, um erwartete Metadatenwerte zu simulieren:

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

Dadurch wird das Verhalten der Health Connect-Implementierung simuliert, bei der diese Werte beim Einfügen von Datensätzen automatisch eingefügt werden.

Für die Testbibliothek müssen Sie diese Health Connect SDK-Abhängigkeit in die Datei „build.gradle“ auf Modulebene einfügen:

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

Bibliothek aktualisieren

Die wichtigsten Schritte sind:

1. Führen Sie ein Upgrade Ihrer Bibliothek auf Version 1.1.0-alpha12 durch.

2. Beim Erstellen der Bibliothek werden Kompilierungsfehler ausgegeben, wenn neue Metadaten erforderlich sind. So beheben Sie diese Fehler und schließen die Migration ab:

   • Beim Erstellen eines Record muss eine Aufzeichnungsmethode angeben werden. Dazu wird eine der in Metadata bereitgestellten Factory-Methoden wie „Metadata.manualEntry()“ oder „Metadata.activelyRecorded(device = Device(...))“ verwendet.
   • Für Daten, die von einem Gerät aufgezeichnet werden, muss ein Gerätetyp angegeben werden, z. B. „Device.TYPE_WATCH“ oder „Device.TYPE_PHONE“.

3. Wenn Ihre App erweiterte Gerätetypen schreibt, müssen Sie sie hinter FEATURE_EXTENTED_DEVICE_TYPES einfügen, um unerwartete TYPE_UNKNOWN auf Geräten zu vermeiden, auf denen die Funktion nicht verfügbar ist.