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. Con el resolución adecuada ayuda a reducir la carga de almacenamiento y, al mismo tiempo, mantiene datos coherentes y exactos. La resolución de datos abarca 2 aspectos:

  1. 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.
  2. Nivel de detalle de los datos escritos: la frecuencia con la que se enviaron los datos muestreados. Por ejemplo, escribe muestras de frecuencia cardíaca cada 5 s. No todos los tipos de datos requiere la misma tasa de muestreo. Actualizar el recuento de pasos no ofrece muchos beneficios. datos 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 una perspectiva de sus datos de salud y actividad física. Frecuencias de las tasas de muestreo debería encontrar un equilibrio entre detalle y rendimiento.

Escribe los datos supervisados durante el día.

Para los datos recopilados de manera continua, como los 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

Calorías

Cada 15 minutos

23:15 - 23:30: 16 calorías

23:30 - 23:45: 16 calorías

23:45 - 00:00 - 16 calorías

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 del entrenamiento o del sueño sesión.

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

Como mínimo, tu aplicación debe seguir las instrucciones de la serie a continuación. Dónde posible, sigue la orientación.

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

Energía

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

Calorías

Cada 1 minuto

Cada segundo

23:14-23:15: 20 calorías

23:16 - 23:17: 20 calorías

23:17 - 23:18: 25 calorías

Total de calorías quemadas

Calorías

Cada 1 minuto

Cada segundo

23:14-23:15: 36 calorías

23:16 - 23:17: 36 calorías

23:17 - 23:18: 41 calorías

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 %