Sviluppare esperienze relative ai segni vitali con Connessione Salute

Se vuoi creare un'app che gestisca i parametri vitali dell'utente, puoi utilizzare Connessione Salute per svolgere attività come:

• Leggere i dati dei parametri vitali, ad esempio pressione sanguigna, frequenza cardiaca e temperatura corporea, da altre app
• Scrivere i dati dei parametri vitali registrati dalla tua 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 dei parametri vitali, incluse le autorizzazioni, i flussi di lavoro di lettura e scrittura e le best practice.

Panoramica: creazione di un tracker completo dei parametri vitali

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

• Richiedere le autorizzazioni appropriate per i tipi di dati dei parametri vitali.
• Scrivere i dati dei parametri vitali utilizzando record come BloodPressureRecord, HeartRateRecord e altri record dei parametri vitali.
• Leggere i dati dei parametri vitali per la visualizzazione, l'analisi o la sincronizzazione.
• Utilizzare il batching per una scrittura e una lettura efficienti dei dati.

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

Prima di iniziare

Prima di implementare le funzionalità dei parametri vitali:

• Integra Health Connect utilizzando la dipendenza appropriata.
• Crea un'istanza di HealthConnectClient.
• Verifica che la tua app implementi i flussi di autorizzazioni di runtime in base alle autorizzazioni relative alla salute.

Concetti principali

I dati dei parametri vitali in Health Connect sono rappresentati da vari tipi di record, ognuno dei quali corrisponde 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 dei parametri vitali sono rappresentati da singoli tipi di record. I tipi comuni includono:

• BloodPressureRecord: rappresenta una singola lettura 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 della frequenza cardiaca 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 la fonte 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 dei parametri vitali possono essere sensibili e le app potrebbero dover scrivere dati in risposta alle misurazioni dei sensori o all'input dell'utente oppure sincronizzare i dati da un backend. Le autorizzazioni sono fondamentali per la gestione dei dati dei parametri vitali.

Autorizzazioni

La tua app deve richiedere le autorizzazioni di Health Connect pertinenti prima di leggere o scrivere i dati dei 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 pressione sanguigna, frequenza cardiaca e 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.

// Create a set of permissions for required data types
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)
)

Utilizza getGrantedPermissions per verificare se la tua app ha già le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Poiché gli utenti possono concedere o revocare le autorizzazioni in qualsiasi momento, la tua app deve controllare le autorizzazioni ogni volta prima di utilizzarle e gestire gli scenari in cui l'autorizzazione viene revocata.

Per richiedere le autorizzazioni, chiama la funzione checkPermissionsAndRun:

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

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 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 i dati dei parametri vitali

Questa sezione descrive come scrivere i dati dei parametri vitali in Health Connect. I dati dei parametri vitali vengono in genere scritti come singoli record. Se scrivi più record contemporaneamente, ad esempio durante la sincronizzazione da un sensore o da 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 in batch

Se la tua app deve scrivere più punti dati, ad esempio durante la sincronizzazione dei dati da un dispositivo connesso o da un servizio di backend, devi eseguire la scrittura in batch 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))
}

Leggere i dati dei parametri vitali

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

Esempio di lettura dei dati 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 Health Connect, 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 ulteriori informazioni, vedi Sincronizzare i dati con Health Connect.

Best practice

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

• Richieste di scrittura in batch: per ridurre il sovraccarico di input/output e preservare la durata della batteria, raggruppa i punti dati in una singola insertRecords chiamata con batch di massimo 1000 record, anziché scrivere ogni punto singolarmente.
• Scrivi spesso durante il monitoraggio in tempo reale: per gli aggiornamenti frequenti dei sensori (come i monitor continui della glicemia o i monitor della frequenza cardiaca), 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 in batch.
• Evita di scrivere dati duplicati: utilizza gli ID client: quando crei i 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 tentativi di sincronizzazione o le reinstallazioni dell'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 nell'intervallo di tempo di sincronizzazione per verificare se i dati della tua app esistono già, in modo da evitare duplicati o la 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 di intervallo 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 Test dei casi d'uso principali.

Strumenti di verifica

• Health Connect Toolbox: utilizza questa app complementare per ispezionare 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 in che modo la tua app gestisce i casi limite, come la revoca delle autorizzazioni o le eccezioni API, senza la necessità di un dispositivo fisico.

Elenco di controllo della qualità

Architettura tipica

Un'implementazione dei parametri vitali include in genere:

Risoluzione dei problemi

Passaggi comuni per il debug