Sincronizza dati

La maggior parte delle app che si integrano con Connessione Salute hanno un proprio datastore che funge da fonte attendibile. Connessione Salute ti offre vari modi per mantenere sincronizzata la tua app.

Assicurati che la tua app:

• Trasferisci i dati nuovi o aggiornati del datastore della tua app a Connessione Salute.
• Recupera le modifiche ai dati da Connessione Salute, che si riflettono nel datastore della tua app.
• Elimina i dati da Connessione Salute quando vengono eliminati nel datastore dell'app.

In ogni caso, assicurati che il processo di sincronizzazione mantenga allineati sia Connessione Salute sia il datastore dell'app.

Dai un feed di dati a Connessione Salute

La prima parte del processo di sincronizzazione consiste nell'inviare i dati dal datastore dell'app al datastore di Connessione Salute.

Prepara i dati

In genere, i record nel datastore dell'app hanno i seguenti dettagli:

• Una chiave univoca, ad esempio UUID.
• Una versione o un timestamp.

Progetta il datastore della tua app per tenere traccia dei dati già inviati a Connessione Salute. A questo scopo, applica la seguente logica:

• Fornisci un elenco delle modifiche e un token che può essere utilizzato per recuperare i record con aggiornamenti dall'emissione dell'ultimo token.
• Monitora l'ultima volta che i dati esportati sono stati modificati.

Questi passaggi sono essenziali per garantire che a Connessione Salute vengano inviati solo dati nuovi o aggiornati.

Scrivi dati in Connessione Salute

Per inserire dati in Connessione Salute, svolgi i seguenti passaggi:

1. Ottieni un elenco di voci nuove o aggiornate dal datastore della tua app.
2. Per ogni voce, crea un oggetto Record appropriato per quel tipo di dati. Ad esempio, crea un oggetto WeightRecord per i dati relativi al peso.

3. Specifica un oggetto Metadata con ogni Record utilizzando la chiave univoca e i dettagli della versione del datastore dell'app. Se i dati non sono sottoposti al controllo delle versioni, puoi utilizzare in alternativa il valore Long del timestamp attuale.

   val record = WeightRecord(
       metadata = Metadata(
           clientRecordId = "<Your record's Client ID>",
           clientRecordVersion = <Your record's version>
       ),
       weight = weight,
       time = time,
       zoneOffset = zoneOffset
   )
   

4. Esegui l'upsert dei dati a Connessione Salute utilizzando insertRecords. L'upsert di dati significa che tutti i dati esistenti in Connessione Salute vengono sovrascritti, purché i valori clientRecordId siano presenti nel datastore di Connessione Salute e il valore di clientRecordVersion sia superiore al valore esistente. In caso contrario, i dati sottoposti a upserted vengono scritti come nuovi dati.

   healthConnectClient.insertRecords(arrayListOf(record))
   

Per saperne di più sulle considerazioni pratiche per l'inserimento di dati, consulta le best practice per Scrittura di dati.

ID di Connessione Salute del negozio

Dopo aver eseguito l'upsert dei tuoi record a Connessione Salute, il datastore dell'app deve archiviare l'id di Connessione Salute per ogni record. In questo modo, la tua app può verificare se ogni modifica in arrivo richiede la creazione di un nuovo record o l'aggiornamento di un record esistente, dopo aver eseguito il pull dei dati.

La funzione insertRecords restituisce un InsertRecordsResponse che contiene l'elenco di valori id. Utilizza la risposta per ottenere gli ID record e archiviarli.

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

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

Nota: puoi sincronizzare i dati senza archiviare id nel datastore dell'app, ma l'app potrebbe ottenere record duplicati di conseguenza. Di conseguenza, sconsigliamo questo approccio.

Estrai i dati da Connessione Salute

La seconda parte del processo di sincronizzazione consiste nel recuperare eventuali modifiche dei dati da Connessione Salute al datastore dell'app. Le modifiche ai dati possono includere aggiornamenti ed eliminazioni.

Recuperare un token per le modifiche

Per ottenere un elenco delle modifiche da recuperare da Connessione Salute, la tua app deve tenere traccia dei token Modifiche. Puoi utilizzarle quando richiedi Modifiche per restituire sia un elenco di modifiche ai dati sia un nuovo token Modifiche da utilizzare la prossima volta.

Per ottenere un token Modifiche, chiama getChangesToken e fornisci i tipi di dati richiesti.

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

Nota: consigliamo di generare token separati per tipo di dati invece di riceverli in blocco per evitare di avere un Exception nel caso in cui una delle autorizzazioni venga revocata.

Verificare la presenza di modifiche ai dati

Ora che hai ottenuto un token Modifiche, utilizzalo per ottenere tutte le Modifiche. Consigliamo di creare un loop per esaminare tutte le modifiche in cui verifica se sono disponibili modifiche ai dati. Ecco la procedura:

1. Chiama getChanges utilizzando il token per ottenere un elenco delle modifiche.
2. Controlla ogni modifica se il tipo di modifica è UpsertionChange o DeletionChange ed esegui le operazioni necessarie.
   • Per UpsertionChange, accetta solo le modifiche che non provengono dall'app di chiamata per assicurarti di non reimportare i dati.
3. Assegna il token Modifiche successivo come nuovo token.
4. Ripeti i passaggi da 1 a 3 finché non ci sono più Modifiche.
5. Archivia il token successivo e prenotalo per un'importazione 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
}

Per conoscere le considerazioni pratiche per il pull dei dati, consulta le best practice per la sincronizzazione dei dati.

Elabora le modifiche ai dati

Applica le modifiche al datastore dell'app. Per UpsertionChange, utilizza id e lastModifiedTime dal relativo metadata per alzare il record. Per DeletionChange, utilizza il id fornito per eliminare il record.

Nota: DeletionChange contiene solo il id del record eliminato e non il tipo di record, per motivi di privacy. In questo modo, puoi specificare un solo tipo di dati per ogni chiamata a getChanges o assicurarti di aver preventivamente archiviato queste informazioni separatamente.

Elimina i dati da Connessione Salute

Quando un utente elimina i propri dati dalla tua app, assicurati che vengano rimossi anche da Connessione Salute. Per farlo, utilizza deleteRecords. Prende un tipo di record e un elenco di valori id e clientRecordId, il che rende conveniente raggruppare più dati per l'eliminazione. È disponibile anche un'alternativa deleteRecords che accetta timeRangeFilter.

Best practice per la sincronizzazione dei dati

Il processo di sincronizzazione è influenzato dai seguenti fattori.

Scadenza del token

Poiché un token Modifiche inutilizzato scade entro 30 giorni, devi utilizzare una strategia di sincronizzazione che evita di perdere informazioni in questo caso. La tua strategia potrebbe includere i seguenti approcci:

• Cerca nel datastore dell'app il record utilizzato più di recente che ha anche un id di Connessione Salute.
• Richiedi a Connessione Salute i record che inizino con un timestamp specifico, quindi inseriscili o aggiornali nel datastore della tua app.
• Richiedi un token delle modifiche per prenotarlo per la prossima volta in cui sarà necessario.

Strategie consigliate per la gestione delle modifiche

Se l'app riceve token Modifiche non validi o scaduti, ti consigliamo le seguenti strategie di gestione a seconda della relativa applicazione nella logica:

• Leggere e deduplicare tutti i dati. Questa è la strategia ideale.
  • Archivia il timestamp dell'ultima lettura di dati di Connessione Salute.
  • Alla scadenza del token, rileggi tutti i dati a partire dal timestamp più recente o degli ultimi 30 giorni. Quindi, deduplicali in base ai dati letti in precedenza utilizzando gli identificatori.
  • Idealmente, implementa gli ID client poiché sono necessari per gli aggiornamenti dei dati.
• Solo i dati letti dal timestamp dell'ultima lettura. Ciò comporta alcune discrepanze nei dati al momento della scadenza del token delle modifiche, ma il periodo di tempo è più breve e potrebbe richiedere da alcune ore a un paio di giorni.
  • Archivia il timestamp dell'ultima lettura di dati di Connessione Salute.
  • Alla scadenza del token, leggi tutti i dati a partire da questo timestamp.
• Elimina e leggi i dati degli ultimi 30 giorni. Ciò è più in linea con ciò che succede alla prima integrazione.
  • Elimina tutti i dati letti dall'app da Connessione Salute negli ultimi 30 giorni.
  • Dopo averli eliminati, leggi di nuovo tutti questi dati.
• Leggi i dati degli ultimi 30 giorni senza deduplicazione. Questa è la strategia meno ideale e comporta la visualizzazione di dati duplicati agli utenti.
  • Elimina tutti i dati letti dall'app da Connessione Salute negli ultimi 30 giorni.
  • Consenti voci duplicate.

Token delle modifiche al tipo di dati

Se la tua app utilizza più di un tipo di dati in modo indipendente, utilizza token di modifica separati per ogni tipo di dati. Utilizza un elenco di più tipi di dati con l'API Changes Sync solo se questi tipi di dati vengono utilizzati insieme o non vengono utilizzati affatto.

Letture in primo piano

Le app possono leggere i dati di Connessione Salute solo quando sono in primo piano. Quando sincronizzi i dati da Connessione Salute, l'accesso a Connessione Salute potrebbe essere interrotto in qualsiasi momento. Ad esempio, l'app deve gestire le interruzioni a metà di una sincronizzazione durante la lettura di una grande quantità di dati da Connessione Salute e deve continuare all'apertura successiva dell'app.

Tempi di importazione

Poiché la tua app non può ricevere notifiche relative ai nuovi dati, controlla la presenza di nuovi dati in due punti:

• Ogni volta che la tua app diventa attiva in primo piano. In questo caso, utilizza gli eventi del ciclo di vita.
• Periodicamente, mentre l'app rimane in primo piano. Avvisa gli utenti quando sono disponibili nuovi dati, consentendo loro di aggiornare il proprio schermo per riflettere le modifiche.