Requisiti dei metadati

Questa guida è compatibile con Health Connect versione 1.2.0-alpha05 e successive.

Sono state apportate modifiche ai metadati in Health Connect per gli sviluppatori che eseguono l'upgrade alla release 1.1.0-alpha12 o versioni successive.

Informazioni sulla biblioteca

L'ID artefatto del plug-in Android per Gradle di Google Maven identifica la libreria Health Connect a cui dovrai eseguire l'upgrade. Aggiungi questa dipendenza dell'SDK Health Connect al file build.gradle a livello di modulo:

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

Modifiche ai metadati

A partire dalla versione 1.1.0-alpha12, sono state introdotte due modifiche ai metadati nell'SDK Health Connect Jetpack per verificare che nell'ecosistema esistano metadati utili aggiuntivi. Se metadata non è incluso nel costruttore Record, potresti visualizzare un errore Constructor internal.

Specificare il metodo di registrazione

Devi specificare i dettagli dei metadati ogni volta che viene istanziato un oggetto di tipo Record().

Quando scrivi dati in Health Connect, devi specificare uno dei quattro metodi di registrazione utilizzando uno dei metodi di fabbrica corrispondenti per creare un'istanza di Metadata:

Ad esempio:

 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

Tipo di dispositivo

Devi specificare un tipo di dispositivo per tutti i dati registrati automaticamente e attivamente. Per saperne di più, consulta la classe Device nella documentazione di Jetpack. I tipi di dispositivo attuali includono:

Alcuni valori di Device.type sono disponibili solo nelle versioni successive di Health Connect. Quando la funzionalità dei tipi di dispositivi estesi non è disponibile, questi tipi vengono trattati come Device.TYPE_UNKNOWN.

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

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

Ad esempio:

 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

Identificatore univoco del dispositivo (UDI)

Per Health Connect su Android 17 (livello API 37.1) o U extension 23 o versioni successive, la classe Device include il supporto per l'identificatore univoco del dispositivo (UDI). L'associazione dei dettagli del modello UDI registrato di un dispositivo medico ai tuoi documenti scritti consente alle applicazioni downstream (come piattaforme di telemedicina o portali clinici) di identificare le letture di livello clinico e distinguerle dai dati generali dei dispositivi indossabili per i consumatori.

Dichiarare l'autorizzazione

Per scrivere i dettagli dell'UDI in Health Connect, devi dichiarare l'autorizzazione WRITE_DEVICE_UDI nel file AndroidManifest.xml della tua app:

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

Tieni presente che WRITE_DEVICE_UDI è un'autorizzazione normale. Devi dichiararla nel manifest, ma non devi richiederla all'utente al runtime. Viene concessa automaticamente alla tua app al momento dell'installazione.

Scrivi solo la parte dell'identificatore del dispositivo (DI)

Un UDI completo è composto da due parti:

• Identificatore del dispositivo (UDI-DI): un identificatore riconosciuto a livello globale assegnato a un modello di dispositivo specifico da un'agenzia di emissione (ad esempio GS1).
• Identificatore di produzione (UDI-PI): attributi specifici dell'unità, ad esempio numeri di serie, numeri di lotto, date di produzione o date di scadenza.

Per proteggere la privacy degli utenti, compila solo la parte UDI-DI del codice in Health Connect. Non includere attributi di identificazione della produzione (ad esempio numeri di serie o numeri di lotto).

Codice di esempio

Nota:puoi impostare l'UDI durante la creazione di un'istanza 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()

Se scrivi dati con un UDI senza dichiarare l'autorizzazione WRITE_DEVICE_UDI, Health Connect genera un errore SecurityException al momento della scrittura.

Utilizzare l'UDI per verificare l'autorizzazione del dispositivo

Health Connect funge da livello di trasporto e non convalida l'autenticità o lo stato di registrazione dell'UDI.

Per i lettori di dati, la presenza di un UDI indica che i dati provengono da un dispositivo medico registrato. Le app di lettura devono eseguire query sui database normativi come il Global Unique Device Identification Database (GUDID) della FDA o EUDAMED dell'UE per verificare le classificazioni dei dispositivi, lo stato di autorizzazione normativa (ad esempio Classe I, II o III) o l'uso previsto specifico.

Snippet aggiornati

Le guide di Health Connect sono state aggiornate ovunque siano necessari nuovi snippet per rispettare i nuovi requisiti dei metadati. Per alcuni esempi, consulta la pagina Scrittura dei dati.

Nuovi metodi per i metadati

I metadati non possono più essere istanziati direttamente, quindi utilizza uno dei metodi di fabbrica per ottenere una nuova istanza di metadati. I metodi di fabbrica verificano che le informazioni sul dispositivo vengano fornite quando un dispositivo o un sensore è stato utilizzato per registrare i dati. Per i dati inseriti manualmente, fornire le informazioni sul dispositivo rimane facoltativo. Ogni funzione ha tre varianti di firma:

• 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

Per ulteriori informazioni, consulta l'Android Open Source Project.

Dati di test

Utilizza la libreria di test e MetadataTestHelper per simulare i valori dei metadati previsti:

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

In questo modo viene simulato il comportamento dell'implementazione di Health Connect, che compila automaticamente questi valori durante l'inserimento dei record.

Per la libreria di test, devi aggiungere questa dipendenza dell'SDK Health Connect al file build.gradle a livello di modulo:

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

Esegui l'upgrade della libreria

I passaggi principali da eseguire sono:

1. Esegui l'upgrade della libreria alla versione 1.1.0-alpha12.

2. Durante la creazione della libreria, verranno generati errori di compilazione nei punti in cui sono necessari nuovi metadati. Per risolvere questi errori e completare la migrazione, verifica di apportare le seguenti modifiche:

   • È obbligatorio specificare un metodo di registrazione durante la creazione di un Record. Ciò avviene utilizzando uno dei metodi di fabbrica forniti in Metadata, ad esempio Metadata.manualEntry() o Metadata.activelyRecorded(device = Device(...)).
   • Per i dati registrati da un dispositivo, è obbligatorio specificare un tipo di dispositivo, ad esempio Device.TYPE_WATCH o Device.TYPE_PHONE.

3. Se la tua app scrive tipi di dispositivi estesi, nascondili dietro FEATURE_EXTENTED_DEVICE_TYPES per evitare TYPE_UNKNOWN imprevisti sui dispositivi in cui la funzionalità non è disponibile.