Se usó la API de Cloud Translation para traducir esta página.

Cómo escribir datos

En esta guía, se explica el proceso de escritura o actualización de datos de Health Connect.

Cómo configurar la estructura de los datos

Antes de escribir los datos, primero debemos configurar los registros. Para más de 50 tipos de datos, cada uno tiene sus respectivas estructuras. Consulta la referencia de Jetpack para obtener más detalles sobre los tipos de datos disponibles.

Registros básicos

El tipo de datos de Pasos de 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.

En el siguiente ejemplo, se muestra cómo configurar los datos del recuento de pasos:

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Registros con unidades de medida

Health Connect puede almacenar valores junto con sus unidades de medida para proporcionar una mayor precisión. Un ejemplo es el tipo de datos de Nutrición que es amplio y extenso. Incluye una gran variedad de campos nutricionales opcionales, que van desde carbohidratos totales hasta vitaminas. Cada dato representa los nutrientes que posiblemente se consumieron como parte de una comida o un alimento.

En el tipo de datos, todos los nutrientes se representan en unidades de Mass, mientras que energy se representa en una unidad de Energy.

En el siguiente ejemplo, se muestra cómo configurar los datos de nutrición de un usuario que comió una banana:

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Registros con datos de series

Health Connect puede almacenar una lista de datos de series. Un ejemplo es el tipo de datos de Frecuencia cardíaca que captura una serie de muestras de latidos detectadas entre lecturas.

En este tipo de datos, el parámetro samples se representa con una lista de muestras de frecuencia cardíaca. Cada muestra contiene un valor beatsPerMinute y un valor time.

En el siguiente ejemplo, se muestra cómo configurar los datos de series de frecuencia cardíaca:

val heartRateRecord = HeartRateRecord(
    startTime = START_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endTime = END_TIME,
    endZoneOffset = END_ZONE_OFFSET,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = START_TIME + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    }
)

Cómo escribir datos

Uno de los flujos de trabajo comunes de Health Connect es la escritura de datos. Para agregar registros, usa insertRecords.

En el siguiente ejemplo, se muestra cómo escribir datos mediante la inserción de recuentos de pasos:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Cómo actualizar datos

Si necesitas cambiar uno o más registros, en especial cuando necesitas sincronizar el almacén de datos de tu app con datos de Health Connect, puedes actualizar los datos. Existen dos maneras de actualizar los datos existentes, que dependen del identificador que se use para encontrar los registros.

Metadatos

Vale la pena examinar la clase Metadata primero, ya que es necesario cuando se actualizan datos. Durante la creación, cada Record de Health Connect tiene un campo metadata. Las siguientes propiedades son relevantes para la sincronización:

Propiedades	Descripción
`id`	Cada `Record` de Health Connect tiene un valor `id` único. Health Connect lo propaga automáticamente cuando insertas un registro nuevo.
`lastModifiedTime`	Cada `Record` también registra la última vez que se modificó el registro. Health Connect lo propaga automáticamente.
`clientRecordId`	Cada `Record` puede tener un ID único asociado para usarlo como referencia en el almacén de datos de tu app. Tu app proporciona este valor.
`clientRecordVersion`	Cuando un registro tiene `clientRecordId`, se puede usar `clientRecordVersion` para permitir que los datos permanezcan sincronizados con la versión del almacén de datos de tu app. Tu app proporciona este valor.

Cómo actualizar mediante el ID de registro

Para actualizar los datos, primero prepara los registros que requieres. Si es necesario, realiza cambios en los registros. Luego, llama a updateRecords para realizar los cambios.

En el siguiente ejemplo, se muestra cómo actualizar los datos. Para este propósito, cada registro tiene sus valores de desplazamiento de zona ajustados en PST.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime,
                    prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        client.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Cómo insertar y actualizar mediante el ID de registro del cliente

Si usas los valores opcionales de ID de registro del cliente y de versión del registro del cliente, te recomendamos que uses insertRecords en lugar de updateRecords.

La función insertRecords tiene la capacidad de insertar y actualizar datos. Si los datos existen en Health Connect según el conjunto determinado de IDs de registro del cliente, se reemplazan. De lo contrario, se escriben como datos nuevos. Esta situación es útil cuando necesitas sincronizar los datos del almacén de datos de tu app con Health Connect.

En el siguiente ejemplo, se muestra cómo realizar una inserción y actualización de los datos que se extraen del almacén de datos de la app:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        // Assign parameters for this record
        metadata = Metadata(
            clientRecordId = cid
        )
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Después de eso, podrás llamar a estas funciones en tu subproceso principal.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Verificación de valores en la versión de registro del cliente

Si tu proceso de inserción y actualización de datos incluye la versión de registro del cliente, Health Connect realiza verificaciones de comparación en los valores de clientRecordVersion. Si la versión de los datos insertados es superior a la versión de los datos existentes, se produce la inserción y la actualización. De lo contrario, el proceso ignorará el cambio y el valor seguirá siendo el mismo.

Para incluir el control de versiones en tus datos, debes proporcionar a Metadata.clientRecordVersion un valor Long basado en tu lógica de control de versiones.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

Las inserciones y las actualizaciones no aumentan automáticamente version, lo que evita cualquier instancia inesperada de reemplazo de datos. De esta manera, debes proporcionarle manualmente un valor más alto.

Prácticas recomendadas para escribir datos

Las apps solo deben escribir datos de origen propio en Health Connect.

Si los datos de tu app se importaron desde otra app, la responsabilidad de escribir sus propios datos en Health Connect recae en la otra app.

También es una buena idea implementar una lógica que maneje excepciones de escritura, como datos que están fuera de los límites o un error interno del sistema. Puedes aplicar tus estrategias de retirada y reintento en un mecanismo de programación de trabajos. Si la escritura en Health Connect no tiene éxito, asegúrate de que la app pueda superar ese punto de exportación. Recuerda informar y registrar errores para facilitar el diagnóstico.

Cuando realizas un seguimiento de los datos, hay algunas sugerencias que puedes seguir según la forma en que tu app escribe datos.

Seguimiento pasivo

Esto incluye las apps que realizan un seguimiento pasivo de la salud o la actividad física en segundo plano de forma continua, como el registro de pasos o de la frecuencia cardíaca.

La app debe escribir datos de forma periódica en Health Connect de las siguientes maneras:

En cada sincronización, solo escribe los datos nuevos y los datos actualizados que se modificaron desde la última sincronización.
Fragmenta las solicitudes a un máximo de 1,000 registros por solicitud de escritura.
Usa WorkManager para programar tareas periódicas en segundo plano, con un período de al menos 15 minutos.

Restringe las tareas para que se ejecuten solo cuando el dispositivo esté inactivo y no tenga poca batería.

val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Seguimiento activo

Esto incluye las apps que realizan un seguimiento basado en eventos, como el ejercicio y el sueño, o las entradas manuales del usuario, como la nutrición. Estos registros se crean cuando la app está en primer plano o en eventos poco frecuentes en los que se usa algunas veces al día.

Asegúrate de que la app no mantenga Health Connect en ejecución durante todo el evento.

Los datos deben escribirse en Health Connect de una de estas dos maneras:

Sincroniza los datos de Health Connect una vez completado el evento. Por ejemplo, sincroniza los datos cuando el usuario finaliza una sesión de ejercicio registrada.
Programa una tarea única con WorkManager para sincronizar los datos más tarde.

Prácticas recomendadas para el nivel de detalle y la frecuencia de las operaciones de escritura

Cuando escribas datos en Health Connect, usa la resolución adecuada. El uso de la resolución adecuada ayuda a reducir la carga de almacenamiento y, al mismo tiempo, mantiene datos coherentes y precisos. La resolución de datos abarca 2 aspectos:

Frecuencia de escrituras: Es la frecuencia con la que tu aplicación envía datos nuevos a Health Connect. Por ejemplo, escribe datos nuevos cada 15 minutos.
Nivel de detalle de los datos escritos: Es la frecuencia con la que se muestrearon los datos enviados. Por ejemplo, escribe muestras de frecuencia cardíaca cada 5 s. No todos los tipos de datos requieren la misma tasa de muestreo. No hay ningún beneficio en actualizar los datos del recuento de pasos cada segundo, en comparación con una cadencia menos frecuente, como cada 60 segundos. Sin embargo, las tasas de muestreo más altas pueden dar a los usuarios un panorama más detallado de sus datos de salud y actividad física. Las frecuencias de las tasas de muestreo deben lograr un equilibrio entre detalle y rendimiento.

Escribe los datos supervisados durante el día.

En el caso de los datos recopilados de manera continua, como pasos, tu aplicación debe escribir en Health Connect al menos cada 15 minutos durante el día.

Tipo de datos	Unidad	Resultado previsto	Ejemplo
Pasos	los pasos	Cada 1 minuto	23:14 - 23:15: 5 pasos 22:16 - 23:17: 22 pasos 23:17 - 23:18: 8 pasos
Ritmo de pasos	pasos/min	Cada 1 minuto	23:14 - 23:15 - 5 p.m. 23:16 - 23:17 - 22 p.m. 23:17 - 23:18 - 8 p.m.
Impulsos en silla de ruedas	empujones	Cada 1 minuto	23:14-23:15: 5 envíos 23:16 - 23:17: 22 envíos 23:17-23:18: 8 envíos
Calorías activas quemadas	Calorías	Cada 15 minutos	23:15 - 23:30: 2 calorías 23:30 - 23:45: 25 calorías 23:45 - 00:00: 5 calorías
Total de calorías quemadas	kcal	Cada 15 minutos	23:15-23:30: 16 kcal 23:30-23:45: 16 kcal 23:45-00:00: 16 kcal
Distancia	km/min	Cada 1 minuto	23:14-23:15 - 0.008 km 23:16 - 23:16 - 0.021 km 23:17 - 23:18 - 0.012 km
Desnivel acumulado	m	Cada 1 minuto	20:36 - 20:37 - 3.048m 20:39 - 20:40 - 3.048m 23:23 - 23:24 - 9.144m
Pisos subidos	pisos	Cada 1 minuto	De 2:14 p.m. a 2:15 p.m.: 5 pisos De 23:16 a 23:16: 22 pisos De 23:17 a 23:18: 8 pisos
Frecuencia cardíaca	ppm	Cada 1 minuto	6:11 a.m. a 55 ppm
variabilidad de la frecuencia cardíacaRmssd	ms	Cada 1 minuto	6:11 a.m. a 23 ms
Frecuencia respiratoria	respiraciones por minuto	Cada 1 minuto	23:14 - 23:15: 60 respiraciones por minuto 23:16 - 23:16: 62 respiraciones por minuto 23:17 - 23:18: 64 respiraciones por minuto
Saturación de oxígeno	%	Cada 1 hora	6:11 % a 95.208 %

Escribir sesiones

Los datos deben escribirse en Health Connect al final de la sesión de entrenamiento o sueño.

Como práctica recomendada, cualquier sesión de sueño o sesión de ejercicio debe escribirse con el dispositivo de registro y los metadatos adecuados, incluido RecordingMethod.

Como mínimo, tu aplicación debe seguir las instrucciones de la columna "previsto" que aparece a continuación. Siempre que sea posible, sigue las "mejores" instrucciones.

Datos registrados durante un ejercicio

Tipo de datos	Unidad	Resultado previsto	Saludos	Ejemplo
Pasos	los pasos	Cada 1 minuto	Cada segundo	23:14-23:15: 5 pasos 22:16 - 23:17: 22 pasos 23:17 - 23:18: 8 pasos
Ritmo de pasos	pasos/min	Cada 1 minuto	Cada segundo	23:14-23:15; 35 p.m. 23:16 - 23:17 - 37 p.m. 23:17 - 23:18 - 40 p.m.
Impulsos en silla de ruedas	empujones	Cada 1 minuto	Cada segundo	23:14-23:15: 5 envíos 23:16 - 23:17: 22 envíos 23:17-23:18: 8 envíos
Ritmo de pedaleo en bicicleta	rpm	Cada 1 minuto	Cada segundo	23:14-23:15; 65 rpm 23:16 - 23:17 - 70 rpm 23:17 - 23:18 - 68 rpm
Potencia	vatios	Cada 1 minuto	Cada segundo	23:14-23:15: 250 W 23:16 - 23:17: 255 W 23:17 - 23:18: 245 W
Velocidad	km/min	Cada 1 minuto	Cada segundo	23:14-23:15: 0.3 km/min 23:16 - 23:17 - 0.4 km/min 23:17 - 23:18 -0.4 km/min
Distancia	km/m	Cada 1 minuto	Cada segundo	23:14-23:15 - 0.008 km 23:16 - 23:16 - 0.021 km 23:17 - 23:18 - 0.012 km
Calorías activas quemadas	kcal	Cada 1 minuto	Cada segundo	23:14-23:15: 20 kcal 23:16 - 23:17: 20 kcal 23:17-23:18: 25 kcal
Total de calorías quemadas	kcal	Cada 1 minuto	Cada segundo	23:14-23:15: 36 kcal 23:16-23:17: 36 kcal 23:17-23:18: 41 kcal
Desnivel acumulado	m	Cada 1 minuto	Cada segundo	20:36 - 20:37 - 3.048m 20:39 - 20:40 - 3.048m 23:23 - 23:24 - 9.144m
EjercicioRoutes	lat./long./alt.	Cada 3 a 5 segundos	Cada segundo
Frecuencia cardíaca	ppm	Cada 1 minuto	Cada segundo	23:14-23:15; 150 ppm 23:16 - 23:17 -152 ppm 23:17 - 23:18 - 155 ppm

Datos registrados durante el sueño

Tipo de datos	Unidad	Muestras esperadas	Ejemplo
Etapas del sueño	de este proceso,	Período detallado por etapa del sueño	23:46 - 23:50: despierto De 2:50 p.m. a 2:56 p.m.: sueño ligero 23:56-00:16: Sueño profundo
Frecuencia cardiaca en reposo	ppm	Valor diario único (se espera a primera hora de la mañana)	6:11 a.m. a 60 ppm
Saturación de oxígeno	%	Valor diario único (se espera a primera hora de la mañana)	6:11 % a 95.208 %