Anforderungen an Metadaten

Dieser Leitfaden ist mit Health Connect-Version 1.2.0-alpha05 oder höher kompatibel.

Für Entwickler, die ein Upgrade auf die Version 1.1.0-alpha12 oder höher durchführen, gibt es Änderungen an den Metadaten in Health Connect.

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

Ab Version 1.1.0-alpha12 wurden zwei Metadatenänderungen am Health Connect Jetpack SDK vorgenommen, 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 du Daten in Health Connect schreibst, musst du eine von vier Aufzeichnungsmethoden angeben. Verwende 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 Unique Device Identifier (UDI). Wenn du die registrierten UDI-Modelldetails eines Medizinprodukts mit deinen schriftlichen Aufzeichnungen verknüpfst, können nachgelagerte Anwendungen (z. B. Telemedizin-Plattformen oder klinische Portale) Messwerte in klinischer Qualität identifizieren und von allgemeinen Daten von Wearables unterscheiden.

Berechtigung deklarieren

Wenn du UDI-Details in Health Connect schreiben möchtest, musst du die Berechtigung WRITE_DEVICE_UDI in der Datei AndroidManifest.xml deiner 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.

Schreibe nur den Teil der Gerätekennung (DI).

Eine vollständige UDI besteht aus zwei Teilen:

• Gerätekennung (UDI-DI): Eine weltweit anerkannte Kennung, die einem bestimmten Gerätemodell von einer Vergabestelle (z. B. GS1) zugewiesen wird.
• Production Identifier (UDI-PI): Gerätespezifische Attribute wie Seriennummern, Chargennummern, Herstellungsdaten oder Ablaufdaten.

Aus Datenschutzgründen solltest du nur den UDI-DI-Teil des Codes in Health Connect angeben. Geben Sie keine Produktkennzeichnungsattribute (wie Serien- 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 UDI schreiben, ohne die Berechtigung WRITE_DEVICE_UDI zu deklarieren, gibt Health Connect beim Schreiben eine SecurityException aus.

UDI zur Überprüfung der Gerätezulassung verwenden

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

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

Snippets aktualisiert

Die Health Connect-Leitfäden wurden überall dort aktualisiert, wo neue Snippets erforderlich sind, um die neuen Metadatenanforderungen zu erfüllen. 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 abzurufen. Die Factory-Methoden prüfen, ob Geräteinformationen bereitgestellt 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 ausgefüllt 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. Aktualisieren Sie Ihre Bibliothek auf 1.1.0-alpha12.

2. Beim Erstellen der Bibliothek werden Kompilierungsfehler ausgegeben, wenn neue Metadaten erforderlich sind. Prüfen Sie, ob Sie die folgenden Änderungen vorgenommen haben, um diese Fehler zu beheben und die Migration abzuschließen:

   • 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 deine App erweiterte Gerätetypen schreibt, schränke sie mit FEATURE_EXTENTED_DEVICE_TYPES ein, um unerwartete TYPE_UNKNOWN auf Geräten zu vermeiden, auf denen die Funktion nicht verfügbar ist.