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. Health Connect ti consente di leggere e scrivere i dati del numero di 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 del conteggio dei passi.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}
HealthConnectManager.kt

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

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}
HealthConnectManager.kt

Lettura dei passi sul dispositivo mobile

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

Per verificare se il conteggio dei passi sul dispositivo è disponibile, assicurati che sul dispositivo sia in esecuzione Android 14 (livello API 34) e che sia installata almeno la versione 20 dell'estensione SDK:

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

Se la tua app legge i conteggi dei passi aggregati utilizzando aggregate e non filtra in base a DataOrigin, i passi sul dispositivo vengono inclusi automaticamente nel totale e non sono necessarie modifiche per l'aggiornamento di giugno 2026.

Modifica dell'attribuzione per i passi sul dispositivo

A partire dall'aggiornamento di giugno 2026, i passi monitorati in modo nativo da Connessione Salute vengono attribuiti a un nome di pacchetto sintetico (SPN), ad esempio com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

In precedenza, i passi integrati venivano attribuiti al nome del pacchetto android. I dati storici sui passi registrati prima di giugno 2026 conservano il nome del pacchetto android.

Gli SPN sono specifici del dispositivo e con ambito per applicazione per proteggere la privacy dell'utente:

• Stabile:l'SPN per il dispositivo attuale è stabile per la tua applicazione.
• Con ambito per applicazione:applicazioni diverse sullo stesso dispositivo vedono SPN diversi per i dati sui passi sul dispositivo.

Esecuzione di query per i passi sul dispositivo

Poiché gli SPN hanno un ambito e sono specifici del dispositivo, non devi codificare i valori SPN. Utilizza invece l'API getCurrentDeviceDataSource() per recuperare l'SPN per il dispositivo attuale.

Sebbene il conteggio dei passi sul dispositivo richieda la versione 20 o successive dell'estensione SDK, l'API getCurrentDeviceDataSource() è disponibile su Android 14 (livello API 34) con la versione 11 o successive dell'estensione SDK.

L'API getCurrentDeviceDataSource() non è ancora disponibile nella libreria Jetpack di Connessione Salute. I seguenti esempi utilizzano invece l'API del framework Android:

import android.content.Context
import android.health.connect.HealthConnectManager

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
val deviceDataSource = healthConnectManager?.getCurrentDeviceDataSource()
val currentDeviceSpn = deviceDataSource?.deviceDataOrigin?.packageName

Se la tua app deve leggere i passi sul dispositivo o se mostra i dati sui passi suddivisi per applicazione o dispositivo di origine, devi eseguire una query per i record in cui DataOrigin è android o corrisponde all'SPN del dispositivo. Se la tua app mostra l'attribuzione per i dati sui passi, utilizza metadata.device per identificare il dispositivo di origine per i singoli record. Per i passi sul dispositivo identificati da un SPN nei dati aggregati, puoi utilizzare i metadati del dispositivo, ad esempio model o manufacturer da DeviceDataSource per l'attribuzione, oppure utilizzare un'etichetta generica come "Il tuo smartphone" per i passi sul dispositivo.

Il seguente esempio mostra come leggere i dati aggregati del conteggio dei passi sul dispositivo filtrando sia android sia l'SPN del dispositivo attuale:

import android.content.Context
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.ext.SdkExtensions
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.StepsRecord
import androidx.health.connect.client.records.metadata.DataOrigin
import androidx.health.connect.client.request.AggregateRequest
import androidx.health.connect.client.time.TimeRangeFilter
import java.time.Instant

suspend fun readDeviceStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    context: Context,
    startTime: Instant,
    endTime: Instant
) {
    // 1. Check if SDK Extension 11+ is available for getCurrentDeviceDataSource()
    val isDataSourceApiAvailable = Build.VERSION.SDK_INT >= Build.VERSION_CODES.U &&
            SdkExtensions.getExtensionVersion(Build.VERSION_CODES.U) >= 11

    try {
        val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)

        // 2. Safely fetch the package name only if API is available and data exists
        val currentDeviceSpn = if (isDataSourceApiAvailable) {
            healthConnectManager?.getCurrentDeviceDataSource()?.deviceDataOrigin?.packageName
        } else {
            null
        }

        val dataOriginFilters = mutableSetOf(DataOrigin("android"))

        // 3. Explicit null-safety check using .let
        currentDeviceSpn?.let {
            dataOriginFilters.add(DataOrigin(it))
        }

        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = dataOriginFilters
            )
        )

        val stepCount = response[StepsRecord.COUNT_TOTAL]

    } catch (e: Exception) {
        // Now this catch block only handles actual runtime exceptions, 
        // rather than Errors from missing methods.
    }
}

Conteggio dei passi sul dispositivo

• Utilizzo dei sensori: Health Connect utilizza il TYPE_STEP_COUNTER sensore 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 Health Connect al massimo una volta al minuto.
• Attribuzione: i passi registrati da questa funzionalità prima di giugno 2026 vengono attribuiti al nome del pacchetto android in DataOrigin. Dopo questa data, vengono attribuiti a un SPN specifico del dispositivo. Consulta Modifica dell'attribuzione per i passi sul dispositivo.
• 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 Health Connect.

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(appContext: Context, workerParams: WorkerParameters) :
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        val healthConnectClient = HealthConnectClient.getOrCreate(applicationContext)
        // Perform background read logic here
        return Result.success()
    }
}
HealthConnectWorker.kt

@OptIn(ExperimentalFeatureAvailabilityApi::class)
fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}
HealthConnectWorker.kt

Il parametro ReadRecordsRequest ha un valore predefinito pageSize di 1000. Se il numero di record in un singolo readResponse supera il 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 nel periodo di tempo richiesto.

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

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
}
HealthConnectManager.kt

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.

Si applicano alcune limitazioni di lettura:

• Per Android 14 e versioni successive

  • Nessun limite storico per un'app che legge i propri dati.
  • Limite di 30 giorni per un'app che legge altri dati.

• Per Android 13 e versioni precedenti

  • Limite di 30 giorni per un'app che legge qualsiasi dato.

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
}
HealthConnectManager.kt

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 di HealthConnectClient elenca le eccezioni che possono essere generate. In generale, la tua app deve gestire le seguenti eccezioni: