Sviluppare esperienze relative ai segni vitali con Connessione Salute

Se vuoi creare un'app che gestisce i parametri vitali degli utenti, puoi utilizzare Connessione Salute per eseguire operazioni quali:

• Leggere i dati dei parametri vitali come pressione sanguigna, battito cardiaco e temperatura corporea da altre app
• Scrivere i dati dei parametri vitali registrati dall'app o dai dispositivi connessi
• Monitorare le tendenze e fornire approfondimenti sulla salute in base ai dati dei parametri vitali

Questa guida descrive come utilizzare i tipi di dati Vitals, trattando autorizzazioni, flussi di lavoro di lettura e scrittura e best practice.

Panoramica: creare un tracker completo dei parametri vitali

Puoi creare un'esperienza completa di monitoraggio dei parametri vitali utilizzando Health Connect seguendo questi passaggi principali:

• Richiedere le autorizzazioni appropriate per i tipi di dati relativi ai parametri vitali.
• Scrittura dei dati dei parametri vitali utilizzando record come BloodPressureRecord, HeartRateRecord e altri record dei parametri vitali.
• Lettura dei dati dei parametri vitali per la visualizzazione, l'analisi o la sincronizzazione.
• Utilizzo del batching per la scrittura e la lettura efficienti dei dati.

Questo workflow consente l'interoperabilità con altre app Health Connect e verifica l'accesso ai dati controllato dall'utente.

Prima di iniziare

Prima di implementare le funzionalità relative ai parametri vitali:

• Integra Health Connect utilizzando la dipendenza appropriata.
• Crea un'istanza HealthConnectClient.
• Verifica che la tua app implementi flussi di autorizzazione in fase di runtime basati sulle autorizzazioni di accesso ai dati sanitari.

Concetti fondamentali

I dati sui parametri vitali in Health Connect sono rappresentati da vari tipi di record, ognuno corrispondente a una misurazione fisiologica specifica. A differenza delle sessioni di allenamento, i parametri vitali vengono spesso registrati come dati puntuali o basati su intervalli.

Tipi di dati dei parametri vitali

I dati di Vitals sono rappresentati da singoli tipi di record. I tipi più comuni includono:

• BloodPressureRecord: rappresenta una singola misurazione della pressione sanguigna, inclusa la pressione sistolica e diastolica e la posizione del corpo.
• HeartRateRecord: rappresenta una serie di misurazioni della frequenza cardiaca.
• RestingHeartRateRecord: rappresenta una singola misurazione del battito cardiaco a riposo.
• BodyTemperatureRecord: rappresenta una singola lettura della temperatura corporea, inclusa la posizione di misurazione.
• BloodGlucoseRecord: rappresenta una singola lettura della glicemia, inclusa la relazione con il pasto e l'origine del campione.
• OxygenSaturationRecord: rappresenta una singola lettura della saturazione di ossigeno nel sangue.
• RespiratoryRateRecord: rappresenta una singola misurazione della frequenza respiratoria.

Per un elenco completo dei tipi di dati, vedi Tipi di dati di Health Connect.

Considerazioni sullo sviluppo

I dati sui parametri vitali possono essere sensibili e le app potrebbero dover scrivere dati in risposta a misurazioni di sensori o input dell'utente oppure sincronizzare dati da un backend. Le autorizzazioni sono fondamentali per la gestione dei dati sui parametri vitali.

Autorizzazioni

La tua app deve richiedere le autorizzazioni di Health Connect pertinenti prima di leggere o scrivere dati sui parametri vitali. Le autorizzazioni comuni per i parametri vitali includono pressione sanguigna, frequenza cardiaca, temperatura corporea, glicemia, saturazione di ossigeno e frequenza respiratoria. È incluso quanto segue:

• Pressione sanguigna:autorizzazioni di lettura e scrittura per BloodPressureRecord.
• Frequenza cardiaca:autorizzazioni di lettura e scrittura per HeartRateRecord.
• Battito cardiaco a riposo:autorizzazioni di lettura e scrittura per RestingHeartRateRecord.
• Temperatura corporea:autorizzazioni di lettura e scrittura per BodyTemperatureRecord.
• Glicemia:autorizzazioni di lettura e scrittura per BloodGlucoseRecord.
• Saturazione di ossigeno:autorizzazioni di lettura e scrittura per OxygenSaturationRecord.
• Frequenza respiratoria:autorizzazioni di lettura e scrittura per RespiratoryRateRecord.

Di seguito è riportato un esempio di come richiedere le autorizzazioni per la pressione sanguigna, la frequenza cardiaca e la temperatura corporea:

Dopo aver creato un'istanza client, la tua app deve richiedere le autorizzazioni all'utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento. A questo scopo, crea un set di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nel set siano dichiarate prima nel manifest di Android.

val permissions =
    setOf(
        HealthPermission.getReadPermission(BloodPressureRecord::class),
        HealthPermission.getWritePermission(BloodPressureRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(BodyTemperatureRecord::class),
        HealthPermission.getWritePermission(BodyTemperatureRecord::class)
    )
HealthConnectManager.kt

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
HealthConnectActivity.kt

Per richiedere le autorizzazioni, chiama la funzione checkPermissionsAndRun:

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

Se devi richiedere le autorizzazioni solo per un singolo tipo di dati, ad esempio la pressione sanguigna, includi solo quel tipo di dati nel set di autorizzazioni:

L'accesso alla pressione sanguigna è protetto dalle seguenti autorizzazioni:

• android.permission.health.READ_BLOOD_PRESSURE
• android.permission.health.WRITE_BLOOD_PRESSURE

Per aggiungere la funzionalità di misurazione della pressione sanguigna alla tua app, inizia richiedendo le autorizzazioni per il tipo di dati BloodPressureRecord.

Ecco l'autorizzazione che devi dichiarare per poter scrivere la pressione sanguigna:

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

Per leggere la pressione sanguigna, devi richiedere le seguenti autorizzazioni:

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

Scrivere dati relativi ai parametri vitali

Questa sezione descrive come scrivere i dati dei parametri vitali su Health Connect. I dati dei parametri vitali vengono in genere scritti come singoli record. Se scrivi più record contemporaneamente, ad esempio la sincronizzazione da un sensore o un backend, utilizza il batching.

Esempio di scrittura di un BloodPressureRecord:

suspend fun writeBloodPressureRecord(healthConnectClient: HealthConnectClient) {
    val record = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    healthConnectClient.insertRecords(listOf(record))
}

Scrittura batch

Se la tua app deve scrivere più punti dati, ad esempio sincronizzare i dati da un dispositivo connesso o da un servizio di backend, devi raggruppare le scritture per migliorare l'efficienza e ridurre il consumo della batteria. Health Connect può gestire fino a 1000 record in una singola richiesta di scrittura.

Il seguente codice mostra come scrivere in batch più record contemporaneamente:

suspend fun writeBatchRecords(healthConnectClient: HealthConnectClient) {
    val bloodPressureRecord = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    val heartRateRecord = HeartRateRecord(
        startTime = Instant.now().minusSeconds(60),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        samples = listOf(HeartRateRecord.Sample(time = Instant.now().minusSeconds(30), beatsPerMinute = 80))
    )
    healthConnectClient.insertRecords(listOf(bloodPressureRecord, heartRateRecord))
}

Lettura dei dati dei parametri vitali

Le app possono leggere i dati di Vitals per visualizzare le misurazioni, analizzare le tendenze o sincronizzare i dati con un server esterno. Per leggere i dati di Vitals, utilizza un ReadRecordsRequest con il tipo di record specifico e filtra per un intervallo di tempo.

Esempio di dati di lettura BloodPressureRecord:

suspend fun readBloodPressureRecords(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = BloodPressureRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (record in response.records) {
        // Process each blood pressure record
        val systolic = record.systolic
        val diastolic = record.diastolic
    }
}

Se devi sincronizzare i dati dei parametri vitali con un server di backend o mantenere aggiornato l'archivio dati della tua app con Connessione Salute, utilizza ChangeLogs. In questo modo puoi recuperare un elenco di record inseriti, aggiornati o eliminati da un momento specifico, il che è più efficiente rispetto al monitoraggio manuale delle modifiche o alla lettura ripetuta di tutti i dati. Per saperne di più, consulta Sincronizzare i dati con Connessione Salute.

Best practice

Segui queste linee guida per migliorare l'affidabilità dei dati e l'esperienza utente:

• Richieste di scrittura batch: per ridurre il sovraccarico di input/output e preservare la durata della batteria, raggruppa i punti dati in una singola chiamata insertRecords con batch di massimo 1000 record, anziché scrivere ogni punto singolarmente.
• Scrivi frequentemente durante il monitoraggio live: per aggiornamenti frequenti dai sensori (come i monitor della glicemia continui o i cardiofrequenzimetri), scrivi i dati in batch a intervalli di massimo 15 minuti per bilanciare gli aggiornamenti in tempo reale con l'efficienza della batteria.
• Utilizza WorkManager per le sincronizzazioni in background: utilizza WorkManager per le scritture posticipate, ad esempio la sincronizzazione dei dati da un dispositivo complementare o da un servizio di backend. Punta a un intervallo di 15 minuti per le scritture batch.
• Evita di scrivere dati duplicati: utilizza gli ID client: quando crei record, imposta un metadata.clientRecordId. Health Connect lo utilizza per identificare i record univoci. Se tenti di scrivere un record con un clientRecordId già esistente, Health Connect ignorerà il duplicato o aggiornerà il record esistente anziché crearne uno nuovo. L'impostazione di un metadata.clientRecordId è il modo più efficace per evitare duplicati durante i nuovi tentativi di sincronizzazione o le reinstallazioni delle app.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• Controlla i dati esistenti: prima di sincronizzare i dati, esegui una query su Health Connect per i record all'interno dell'intervallo di tempo di sincronizzazione per verificare se i dati della tua app esistono già, in modo da evitare duplicati o sovrascrittura di dati più recenti.
• Fornisci motivazioni chiare per l'autorizzazione: utilizza il flusso Permission.createIntent per spiegare perché la tua app ha bisogno di accedere ai dati sulla salute, ad esempio: "Per monitorare le tendenze della pressione sanguigna e fornire approfondimenti".
• Allinea i timestamp alle misurazioni: verifica che i timestamp dei record riflettano con precisione il momento in cui sono state eseguite le misurazioni. Per i dati a intervalli come HeartRateRecord, verifica che startTime e endTime siano corretti.

Test

Per verificare la correttezza dei dati e un'esperienza utente di alta qualità, segui queste strategie di test e consulta la documentazione ufficiale relativa ai principali casi d'uso dei test.

Strumenti di verifica

• Strumenti per Connessione Salute: utilizza questa app complementare per esaminare manualmente i record, eliminare i dati di test e simulare le modifiche al database. È il modo migliore per verificare che i record vengano archiviati correttamente.
• Test delle unità con FakeHealthConnectClient: utilizza la libreria di test per verificare come la tua app gestisce i casi limite, come la revoca delle autorizzazioni o le eccezioni API, senza bisogno di un dispositivo fisico.

Elenco di controllo della qualità

Architettura tipica

Un'implementazione di Vitals in genere include:

Risoluzione dei problemi

Passaggi di debug comuni