Cómo leer datos sin procesar

En el siguiente ejemplo, se muestra cómo leer datos sin procesar como parte de un flujo de trabajo común.

Lee datos

Health Connect permite que las apps lean datos del almacén de datos cuando la app está en primer plano y en segundo plano:

• Lecturas en primer plano: Normalmente, puedes leer datos de Health Connect cuando tu app está en primer plano. En estos casos, puedes considerar usar un servicio en primer plano para ejecutar esta operación en caso de que el usuario o el sistema pongan tu app en segundo plano durante una operación de lectura.

• Lecturas en segundo plano: Si solicitas un permiso adicional al usuario, puedes leer datos después de que el usuario o el sistema coloquen tu app en segundo plano. Consulta el ejemplo de lectura en segundo plano completo.

El tipo de datos de Pasos en Health Connect captura la cantidad de pasos que dio un usuario entre cada medición. El recuento de pasos representa una medición común en todas las plataformas de salud, actividad física y bienestar. Health Connect te permite leer y escribir datos de recuento de pasos.

Para leer registros, crea un ReadRecordsRequest e infórmalo cuando llames a readRecords.

En el siguiente ejemplo, se muestra cómo leer los datos del recuento de pasos para un usuario en un período determinado. Para ver un ejemplo extendido con SensorManager, consulta la guía de datos de recuento de pasos.

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

También puedes leer tus datos de forma agregada con 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

Leer los pasos en dispositivos móviles

Con Android 14 (nivel de API 34) y la versión 20 o posterior de la extensión del SDK, Health Connect proporciona el recuento de pasos integrado en el dispositivo. Si alguna app tiene el permiso READ_STEPS, Health Connect comienza a capturar los pasos del dispositivo Android y los usuarios ven los datos de pasos agregados automáticamente a las entradas de Pasos de Health Connect.

Para verificar si el recuento de pasos integrado en el dispositivo está disponible, verifica que el dispositivo ejecute Android 14 (nivel de API 34) y tenga al menos la versión 20 de la extensión del SDK:

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

Si tu app lee los recuentos de pasos agregados con aggregate y no filtra por DataOrigin, los pasos integrados en el dispositivo se incluyen automáticamente en el total, y no se requieren cambios para la actualización de junio de 2026.

Cambio en la atribución de los pasos integrado en el dispositivo

A partir de la actualización de junio de 2026, los pasos que se registren de forma nativa con Health Connect se atribuirán a un nombre de paquete sintético (SPN), como com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Anteriormente, los pasos integrados se atribuían al nombre del paquete android. Los datos históricos de pasos registrados antes de junio de 2026 conservan el nombre del paquete android.

Los SPN son específicos del dispositivo y se definen por aplicación para proteger la privacidad del usuario:

• Estable: El SPN del dispositivo actual es estable para tu aplicación.
• Específico de la aplicación: Diferentes aplicaciones en el mismo dispositivo ven diferentes SPN para los datos de pasos integrados en el dispositivo.

Cómo consultar los pasos integrados en el dispositivo

Como los SPN son específicos del dispositivo y tienen un alcance limitado, no debes codificar de forma rígida los valores de SPN. En su lugar, usa la API de getCurrentDeviceDataSource() para recuperar el SPN del dispositivo actual.

Si bien el recuento de pasos integrado en el dispositivo requiere la versión 20 o posterior de la extensión del SDK, la API de getCurrentDeviceDataSource() está disponible en Android 14 (nivel de API 34) con la versión 11 o posterior de la extensión del SDK.

La API de getCurrentDeviceDataSource() aún no está disponible en la biblioteca de Jetpack de Health Connect. En los siguientes ejemplos, se usa la API del framework de 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

Si tu app necesita leer los pasos registrados en el dispositivo o si muestra datos de pasos desglosados por aplicación o dispositivo fuente, debes consultar los registros en los que DataOrigin sea android o coincida con el SPN del dispositivo. Si tu app muestra la atribución de los datos de pasos, usa metadata.device para identificar el dispositivo fuente de los registros individuales. En el caso de los pasos integrados en el dispositivo identificados por un SPN en los datos agregados, puedes usar metadatos del dispositivo, como model o manufacturer de DeviceDataSource para la atribución, o bien usar una etiqueta genérica, como "Tu teléfono", para los pasos integrados en el dispositivo.

En el siguiente ejemplo, se muestra cómo leer los datos agregados del recuento de pasos en el dispositivo filtrando tanto android como el SPN del dispositivo actual:

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

Recuento de pasos integrado en el dispositivo

• Uso del sensor: Health Connect utiliza el sensor TYPE_STEP_COUNTER de SensorManager. Este sensor está optimizado para un bajo consumo de energía, lo que lo hace ideal para el seguimiento continuo de pasos en segundo plano.
• Granularidad de los datos: Para conservar la batería, los datos de pasos suelen agruparse y escribirse en la base de datos de Health Connect con una frecuencia no mayor a una vez por minuto.
• Atribución: Los pasos que registra esta función antes de junio de 2026 se atribuyen al nombre de paquete android en DataOrigin. Después de esta fecha, se atribuyen a un SPN específico del dispositivo. Consulta Cambio en la atribución para los pasos integrado en el dispositivo.
• Activación: El mecanismo de recuento de pasos integrado en el dispositivo solo está activo cuando al menos una aplicación del dispositivo tiene el permiso READ_STEPS en Health Connect.

Ejemplo de lectura en segundo plano

Para leer datos en segundo plano, declara el siguiente permiso en tu archivo de manifiesto:

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

En el siguiente ejemplo, se muestra cómo leer los datos del recuento de pasos en segundo plano para un usuario en un período determinado con 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

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

El parámetro ReadRecordsRequest tiene un valor predeterminado pageSize de 1,000. Si la cantidad de registros en un solo readResponse supera el pageSize de la solicitud, debes iterar todas las páginas de la respuesta para recuperar todos los registros con pageToken. Sin embargo, ten cuidado para evitar problemas relacionados con la limitación de frecuencia.

Ejemplo de lectura de pageToken

Se recomienda usar pageToken para leer registros y recuperar todos los datos disponibles del período solicitado.

En el siguiente ejemplo, se muestra cómo leer todos los registros hasta que se agoten todos los tokens de página:

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

Lectura de datos pasados

Si una app escribió registros en Health Connect anteriormente, es posible que la app lea datos históricos. Esto se aplica a situaciones en las que la app necesita volver a sincronizarse con Health Connect cuando el usuario la reinstala.

Se aplican algunas restricciones de lectura:

• Para Android 14 y versiones posteriores

  • No hay límite histórico para que una app lea sus propios datos.
  • Límite de 30 días para que una app lea otros datos

• Para Android 13 y versiones anteriores

  • Límite de 30 días para que la app lea cualquier dato

Las restricciones se pueden quitar solicitando un permiso de lectura.

Para leer los datos históricos, debes indicar el nombre del paquete como un objeto DataOrigin en el parámetro dataOriginFilter de tu ReadRecordsRequest.

En el siguiente ejemplo, se muestra cómo indicar un nombre de paquete cuando se leen los registros de frecuencia cardíaca:

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

Lectura del identificador único del dispositivo (UDI)

En el caso de los registros que provienen de dispositivos médicos, las aplicaciones de lectura pueden extraer la parte del identificador del dispositivo (DI) del identificador único del dispositivo (UDI) de los metadatos del dispositivo. Para obtener orientación sobre cómo procesar esta información y compararla con las bases de datos reglamentarias, consulta la guía de metadatos.

Cómo leer datos anteriores a 30 días

De forma predeterminada, todas las aplicaciones pueden leer datos de Health Connect hasta 30 días antes del otorgamiento de cualquier permiso.

Si necesitas extender los permisos de lectura más allá de cualquiera de las restricciones predeterminadas, solicita el PERMISSION_READ_HEALTH_DATA_HISTORY. De lo contrario, sin este permiso, cualquier intento de leer registros con más de 30 días de antigüedad generará un error.

Historial de permisos de una app borrada

Si un usuario borra tu app, se revocarán todos los permisos, incluido el permiso de historial. Si el usuario vuelve a instalar tu app y le otorga permiso de nuevo, se aplicarán las mismas restricciones predeterminadas, y tu app podrá leer datos de Health Connect hasta 30 días antes de esa fecha nueva.

Por ejemplo, supongamos que el usuario borra tu app el 10 de mayo de 2023 y, luego, la vuelve a instalar el 15 de mayo de 2023 y otorga permisos de lectura. Ahora, la fecha más antigua de la que tu app puede leer datos de forma predeterminada es el 15 de abril de 2023.

Cómo controlar excepciones

Health Connect genera excepciones estándar para las operaciones de CRUD cuando se produce un problema. Tu app debe detectar y controlar cada una de estas excepciones según corresponda.

Cada método de HealthConnectClient enumera las excepciones que se pueden generar. En general, tu app debe controlar las siguientes excepciones: