Lettura di dati non elaborati

L'esempio seguente mostra come leggere i dati non elaborati nell'ambito del flusso di lavoro comune.

Lettura di dati

Connessione Salute consente alle app di leggere i dati dall'archivio dati quando l'app è in primo piano e in background:

• Letture in primo piano: in genere puoi leggere i dati da Connessione Salute quando la tua app è in primo piano. In questi casi, potresti usare un servizio in primo piano per eseguire questa operazione se l'utente o il sistema mette la tua app in background durante un'operazione di lettura.

• Letture in background: se richiedi un'autorizzazione aggiuntiva all'utente, puoi leggere i dati dopo che l'utente o il sistema avrà messo la tua app in background. Vedi l'esempio completo di lettura in background.

Il tipo di dati Passi in Connessione Salute acquisisce il numero di passi che un utente ha compiuto tra le letture. Il conteggio dei passi rappresenta una misurazione comune su piattaforme per la salute, il fitness e il benessere. Connessione Salute ti consente di leggere e scrivere i dati relativi al conteggio dei passi.

Per leggere i record, crea un ReadRecordsRequest e forniscilo quando chiami readRecords.

Il seguente esempio mostra come leggere i dati del conteggio dei passi per un utente in un determinato lasso di tempo. Per un esempio esteso con SensorManager, consulta la guida ai dati sul conteggio dei passi.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

Puoi anche leggere i tuoi dati in modo aggregato utilizzando aggregate.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Lettura dei passi da dispositivo mobile

Con Android 14 (livello API 34) e l'estensione SDK versione 20 o successive, Connessione Salute fornisce il conteggio dei passi sul dispositivo. Se a un'app è stata concessa l'autorizzazione READ_STEPS, Connessione Salute inizia ad acquisire i passi dal dispositivo Android e gli utenti vedono i dati dei passi aggiunti automaticamente alle voci Passi di Connessione Salute.

Per verificare se il conteggio dei passi sul dispositivo è disponibile, devi verificare che il dispositivo esegua Android 14 (livello API 34) e abbia almeno l'estensione SDK versione 20. Puoi utilizzare il seguente codice:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

I passi mobile acquisiti da Connessione Salute hanno il valore DataOrigin impostato sul nome del pacchetto android. Se la tua app legge semplicemente i conteggi dei passi aggregati utilizzando aggregate e non filtra per DataOrigin, i passi sul dispositivo vengono inclusi automaticamente nel totale.

Se la tua app deve leggere i passi sul dispositivo o se mostra i dati dei passi suddivisi per applicazione o dispositivo di origine, puoi eseguire query per i record in cui DataOrigin è android. Se la tua app mostra l'attribuzione per i dati dei passi, devi attribuire i dati del pacchetto Android al dispositivo attuale. Puoi farlo utilizzando un'etichetta come"Il tuo smartphone", recuperando il nome del dispositivo con Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) o esaminando il campo Device nei metadati del record.

Il seguente esempio mostra come leggere i dati aggregati del conteggio dei passi da dispositivo mobile filtrando in base all'origine dati android:

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Conteggio dei passi sul dispositivo

Approfondimento della funzionalità di conteggio dei passi sul dispositivo:

• Utilizzo dei sensori: Connessione Salute utilizza il sensore TYPE_STEP_COUNTER di SensorManager. Questo sensore è ottimizzato per un basso consumo energetico, il che lo rende ideale per il monitoraggio continuo dei passi in background.
• Granularità dei dati: per preservare la durata della batteria, i dati sui passi vengono in genere raggruppati e scritti nel database di Connessione Salute non più di una volta al minuto.
• Attribuzione: come accennato in precedenza, tutti i passaggi registrati da questa funzionalità sul dispositivo vengono attribuiti al nome del pacchetto android in DataOrigin.
• Attivazione: il meccanismo di conteggio dei passi sul dispositivo è attivo solo quando ad almeno un'applicazione sul dispositivo è stata concessa l'autorizzazione READ_STEPS in Connessione Salute.

Esempio di lettura in background

Per leggere i dati in background, dichiara la seguente autorizzazione nel file manifest:

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

Il seguente esempio mostra come leggere i dati del conteggio dei passi in background per un utente in un determinato lasso di tempo utilizzando WorkManager:

class ScheduleWorker(private val appContext: Context, workerParams: WorkerParameters):
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        // Read data and process it.
        ...

        // Return success indicating successful data retrieval
        return Result.success()
    }
}

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

    // Check if necessary permission is granted
    val grantedPermissions = healthConnectClient.permissionController.getGrantedPermissions()

    if (PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND !in grantedPermissions) {
        // Perform read in foreground
        ...
    } else {
        // Schedule the periodic work request in background
        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
} else {
  // Background reading is not available, perform read in foreground
  ...
}

Il parametro ReadRecordsRequest ha un valore predefinito pageSize di 1000. Se il numero di record in una singola readResponse supera la pageSize della richiesta, devi scorrere tutte le pagine della risposta per recuperare tutti i record utilizzando pageToken. Tuttavia, fai attenzione a evitare problemi di limitazione della frequenza.

Esempio di lettura di pageToken

Ti consigliamo di utilizzare pageToken per leggere i record e recuperare tutti i dati disponibili del periodo di tempo richiesto.

L'esempio seguente mostra come leggere tutti i record finché tutti i token di pagina non sono stati esauriti:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}

Per informazioni sulle best practice per la lettura di set di dati di grandi dimensioni, consulta Pianificare di evitare la limitazione della frequenza.

Leggere i dati scritti in precedenza

Se un'app ha già scritto dei dati su Connessione Salute in passato, è possibile che la stessa app possa leggere anche i dati storici. Ciò è applicabile negli scenari in cui l'app deve essere risincronizzata con Connessione Salute dopo che l'utente l'ha reinstallata.

Sono previste alcune limitazioni di lettura:

• Per Android 14 e versioni successive

  • Nessun limite storico alla lettura dei propri dati da parte di un'app.
  • Limite di 30 giorni per la lettura di altri dati da parte di un'app.

• Per Android 13 e versioni precedenti

  • Limite di 30 giorni per la lettura di qualsiasi dato da parte dell'app.

Le limitazioni possono essere rimosse richiedendo un'autorizzazione in lettura.

Per leggere i dati storici, devi indicare il nome del pacchetto come oggetto DataOrigin nel parametro dataOriginFilter della tua ReadRecordsRequest.

L'esempio seguente mostra come indicare il nome di un pacchetto durante la lettura dei record della frequenza cardiaca:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}

Leggere i dati più vecchi di 30 giorni

Per impostazione predefinita, tutte le applicazioni possono leggere i dati da Connessione Salute fino a 30 giorni prima del momento in cui è stata concessa la prima autorizzazione.

Se hai bisogno di estendere le autorizzazioni in lettura oltre lelimitazioni predefinite, richiedi PERMISSION_READ_HEALTH_DATA_HISTORY. In caso contrario, senza questa autorizzazione, ogni tentativo di lettura dei record più vecchi di 30 giorni genererà un errore.

Cronologia delle autorizzazioni per un'app eliminata

Se un utente elimina la tua app, tutte le autorizzazioni, inclusa quella della cronologia, vengono revocate. Se l'utente reinstalla la tua app e concede nuovamente l'autorizzazione, si applicano le stesse limitazioni predefinite e la tua app può leggere i dati di Connessione Salute fino a 30 giorni precedenti a questa nuova data.

Ad esempio, supponiamo che l'utente elimini la tua app il 10 maggio 2023 e poi la reinstalli il 15 maggio 2023, concedendo le autorizzazioni di lettura. La data più recente a partire dalla quale la tua app può leggere i dati per impostazione predefinita è il 15 aprile 2023.

Gestire le eccezioni

Connessione Salute genera eccezioni standard per le operazioni CRUD quando si verifica un problema. La tua app deve rilevare e gestire ciascuna di queste eccezioni in modo appropriato.

Ogni metodo in HealthConnectClient elenca le eccezioni che possono essere generate. In generale, la tua app deve gestire le seguenti eccezioni: