Cómo sincronizar datos

La mayoría de las apps que se integran con Health Connect tienen su propio almacén de datos que sirve como fuente de información. Health Connect proporciona formas de mantener tu app sincronizada.

Asegúrate de que tu app haga lo siguiente:

  • Ingresar datos nuevos o actualizados del almacén de datos de tu app a Health Connect.
  • Extraer los cambios de datos de Health Connect, que se reflejan en el almacén de datos de tu app.
  • Borrar datos de Health Connect cuando se borran del almacén de datos de tu app.

En cada caso, asegúrate de que el proceso de sincronización mantenga alineados Health Connect y el almacén de datos de tu app.

Cómo ingresar datos en Health Connect

La primera parte del proceso de sincronización consiste en enviar datos desde el almacén de datos de tu app al almacén de datos de Health Connect.

Cómo preparar los datos

Por lo general, los registros del almacén de datos de tu app tienen los siguientes detalles:

  • Una clave única, como un UUID
  • Una versión o una marca de tiempo

Diseña el almacén de datos de tu app para realizar un seguimiento de los datos que ya se ingresaron a Health Connect. Para lograrlo, aplica la siguiente lógica:

  • Proporciona una lista de cambios y un token que se pueda usar para recuperar registros que tengan actualizaciones desde que se emitió el último token.
  • Realiza un seguimiento de la última vez que se modificaron los datos exportados.

Estos pasos son esenciales para garantizar que solo se envíen datos nuevos o actualizados a Health Connect.

Cómo escribir datos en Health Connect

Para ingresar datos en Health Connect, sigue estos pasos:

  1. Obtén la lista de las entradas nuevas o actualizadas del almacén de datos de tu app.
  2. Para cada entrada, crea un objeto Record apropiado para ese tipo de datos. Por ejemplo, crea un objeto WeightRecord para datos relacionados con el peso.
  3. Especifica un objeto Metadata con cada Record mediante los detalles únicos de la versión y la clave del almacén de datos de tu app. Si tus datos no tienen control de versiones, puedes usar el valor Long de la marca de tiempo actual como alternativa.

    val record = WeightRecord(
        metadata = Metadata(
            clientRecordId = "<Your record's Client ID>",
            clientRecordVersion = <Your record's version>
        ),
        weight = weight,
        time = time,
        zoneOffset = zoneOffset
    )
    
  4. Inserta y actualiza datos a Health Connect con insertRecords. La inserción y actualización de datos implica que los datos existentes de Health Connect se reemplazan siempre que los valores de clientRecordId existan en el almacén de datos de Health Connect, y el valor de clientRecordVersion sea mayor que el valor existente. De lo contrario, los datos insertados y actualizados se escriben como datos nuevos.

    healthConnectClient.insertRecords(arrayListOf(record))
    

Si quieres conocer las consideraciones prácticas para agregar datos, consulta las prácticas recomendadas sobre Cómo escribir datos.

Cómo almacenar IDs de Health Connect

Después de insertar y actualizar tus registros en Health Connect, el almacén de datos de tu app debe almacenar el id de Health Connect de cada registro. Esto permite que la app verifique si cada cambio entrante requiere crear un registro nuevo o actualizar un registro existente después de extraer los datos.

La función insertRecords muestra un InsertRecordsResponse que contiene la lista de valores id. Usa la respuesta para obtener los IDs de registro y almacenarlos.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

Cómo extraer datos de Health Connect

La segunda parte del proceso de sincronización consiste en extraer cualquier cambio de datos de Health Connect al almacén de datos de la app. Los cambios de datos pueden incluir actualizaciones y eliminaciones.

Cómo obtener un token de cambios

A fin de obtener una lista de cambios para extraer de Health Connect, tu app debe hacer un seguimiento de los tokens de Cambios. Puedes usarlos cuando solicites Cambios para mostrar una lista de cambios de datos y un token de Cambios nuevo que se usará la próxima vez.

Para obtener un token de Cambios, llama a getChangesToken y proporciona los tipos de datos obligatorios.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

Cómo verificar si hay cambios en los datos

Ahora que obtuviste un token de Cambios, úsalo para obtener todos los Cambios. Te recomendamos que crees un bucle para revisar todos los Cambios donde se verifique si hay cambios de datos disponibles. Sigue estos pasos:

  1. Llama a getChanges con el token para obtener una lista de Cambios.
  2. Verifica cada cambio para saber si su tipo de cambio es UpsertionChange o DeletionChange, y realiza las operaciones necesarias.
    • Para UpsertionChange, solo realiza cambios que no provengan de la app que realiza la llamada a fin de asegurarte de no volver a importar datos.
  3. Asigna el siguiente token de Cambios como tu token nuevo.
  4. Repite los pasos 1 a 3 hasta que no queden Cambios.
  5. Almacena el siguiente token y guárdalo para una importación futura.
suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

Si deseas conocer las consideraciones prácticas sobre la extracción de datos, consulta las prácticas recomendadas de sincronización de datos.

Cómo procesar cambios en los datos

Refleja los cambios que se realizaron en el almacén de datos de tu app. Para UpsertionChange, usa el id y la lastModifiedTime de sus metadata a fin de insertar y actualizar el registro. En DeletionChange, usa el id proporcionado para borrar el registro.

Cómo borrar datos de Health Connect

Cuando un usuario borre sus propios datos de tu app, asegúrate de que los datos también se quiten de Health Connect. Usa deleteRecords para hacerlo. Toma un tipo de registro y una lista de id y clientRecordId de salida, lo que hace que sea conveniente agrupar múltiples datos para su eliminación. Los deleteRecords alternativo que toma un objeto timeRangeFilter también está disponible.

Prácticas recomendadas para sincronizar datos

Los siguientes factores afectan el proceso de sincronización:

Vencimiento del token

Como un token de cambios sin usar vence en 30 días, debes implementar una estrategia de sincronización que evite perder información en tal caso. Tu estrategia podría incluir los siguientes enfoques:

  • Busca en el almacén de datos de la app el registro consumido más reciente que también tenga un id de Health Connect.
  • Solicita registros de Health Connect que comiencen con una marca de tiempo específica y, luego, insértalos o actualízalos en el almacén de datos de la app.
  • Solicita un token de cambios para reservarlo para la próxima vez que lo necesites.

Estrategias recomendadas de administración de cambios

Si la app obtiene tokens de cambios no válidos o vencidos, te recomendamos que sigas las siguientes estrategias de administración según su aplicación en tu lógica:

  • Lee y anula la duplicación de todos los datos. Esta es la estrategia ideal.
    • Almacena la marca de tiempo de la última vez que leyeron datos de Health Connect.
    • Cuando venza el token, vuelve a leer todos los datos de la marca de tiempo más reciente o de los últimos 30 días. Luego, anula los duplicados en función de los datos leídos anteriormente usando identificadores.
    • Lo ideal es implementar los IDs de cliente, ya que son necesarios para las actualizaciones de datos.
  • Solo lee los datos desde la última marca de tiempo de lectura. Esto genera algunas discrepancias de datos alrededor del tiempo de vencimiento del token de cambios, pero el período es más corto y puede tardar unas horas o un par de días.
    • Almacena la marca de tiempo de la última vez que leyeron datos de Health Connect.
    • Cuando venza el token, lee todos los datos desde esa marca de tiempo en adelante.
  • Borra los datos de los últimos 30 días y, luego, léelos. Esto se alinea más con lo que sucede en la primera integración.
    • Borra todos los datos que haya leído la app de Health Connect durante los últimos 30 días.
    • Una vez borrados, vuelve a leer todos estos datos.
  • Lee los datos de los últimos 30 días sin anular la duplicación. Esta es la estrategia menos ideal y genera que se muestren datos duplicados a los usuarios.
    • Borra todos los datos que haya leído la app de Health Connect durante los últimos 30 días.
    • Permite entradas duplicadas.

Tokens de cambios para tipos de datos

Si la app consume más de un tipo de datos de forma independiente, usa tokens de cambios separados para cada tipo de datos. Solo usa una lista de varios tipos de datos con la API de Changes Sync si estos tipos de datos se consumen juntos o no se consumen en absoluto.

Lecturas en primer plano

Las apps solo pueden leer datos de Health Connect mientras se encuentran en primer plano. Cuando sincronizas los datos de Health Connect, el acceso a Health Connect puede interrumpirse en cualquier momento. Por ejemplo, la app debe controlar las interrupciones durante una sincronización cuando lee una gran cantidad de datos de Health Connect y continuar la próxima vez que se abra.

Tiempos de importación

Dado que no se puede notificar a la app sobre datos nuevos, comprueba los datos nuevos en dos puntos:

  • Cada vez que tu app se activa en primer plano. En este caso, usa eventos de ciclo de vida.
  • Periódicamente, mientras la app permanece en primer plano Notifica a los usuarios cuando haya datos nuevos disponibles. Eso les permitirá actualizar la pantalla para reflejar los cambios.