Sincronizza dati

La maggior parte delle app integrate con Connessione Salute ha un proprio data store che funge da fonte attendibile. Connessione Salute offre modi per mantenere sincronizzata la tua app.

Assicurati che la tua app:

• Invia dati nuovi o aggiornati dal data store dell'app a Connessione Salute.
• Estrae le modifiche ai dati da Connessione Salute, che vengono applicate al datastore della tua app.
• Elimina i dati da Connessione Salute quando vengono eliminati nel data store dell'app.

In ogni caso, assicurati che la procedura di sincronizzazione mantenga in linea sia Connessione Salute sia il datastore della tua app.

Eseguire il feed dei dati in Connessione Salute

La prima parte del processo di sincronizzazione consiste nell'eseguire il feed dei dati dal datastore della tua app al datastore di Connessione Salute.

Preparare i dati

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

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

Progetta il data store della tua app per tenere traccia dei dati che sono già stati inviati a Connessione Salute. Per farlo, applica la seguente logica:

• Fornisci un elenco di modifiche e un token che può essere utilizzato per recuperare i record aggiornati 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.

Scrivere dati in Connessione Salute

Per inviare dati a Connessione Salute, svolgi i seguenti passaggi:

1. Ottieni un elenco di voci nuove o aggiornate dal data store 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 della tua app. Se i dati non sono sottoposti a versionamento, in alternativa puoi utilizzare il valore Long del timestamp corrente.

   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 in Connessione Salute utilizzando insertRecords. L'upsert dei dati significa che tutti i dati esistenti in Connessione Salute vengono sovrascritti, a condizione che i valori clientRecordId esistano nel data store di Connessione Salute e che clientRecordVersion sia superiore al valore esistente. In caso contrario, i dati sottoposti ad upsert vengono scritti come nuovi dati.

   healthConnectClient.insertRecords(arrayListOf(record))
   

Per informazioni sulle considerazioni pratiche per l'inserimento dei dati, consulta le best practice per la scrittura dei dati.

Memorizzare gli ID Connessione Salute

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

La funzione insertRecords restituisce un InsertRecordsResponse contenente l'elenco dei valori id. Utilizza la risposta per recuperare gli ID record e memorizzarli.

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

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

Nota: puoi sincronizzare i dati senza memorizzare id nel datastore della tua app, ma come risultato la tua app potrebbe ricevere record duplicati. Di conseguenza, sconsigliamo di scegliere questo approccio.

Estrarre i dati da Connessione Salute

La seconda parte del processo di sincronizzazione consiste nel recuperare eventuali modifiche ai dati da Connessione Salute al data store della tua app. Le modifiche ai dati possono includere aggiornamenti ed eliminazioni.

Ottenere un token di modifiche

Per ottenere un elenco di modifiche da estrarre da Connessione Salute, la tua app deve monitorare i token Modifiche. Puoi utilizzarli 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 Changes, chiama getChangesToken e fornisci i tipi di dati richiesti.

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

Nota: ti consigliamo di ottenere token separati per tipo di dati anziché in blocco per evitare di avere un Exception nel caso in cui una delle autorizzazioni venga revocata.

Controllare le modifiche ai dati

Ora che hai ottenuto un token Modifiche, utilizzalo per ottenere tutte le Modifiche. Ti consigliamo di creare un ciclo per esaminare tutte le modifiche in cui viene controllato se sono disponibili modifiche ai dati. Ecco i passaggi da seguire:

1. Chiama getChanges utilizzando il token per ottenere un elenco di modifiche.
2. Controlla ogni modifica per verificare se si tratta di un valore UpsertionChange o DeletionChange e svolgi le operazioni necessarie.
   • Per UpsertionChange, prendi in considerazione solo le modifiche che non provengono dall'app di chiamata per assicurarti di non importare nuovamente i dati.
3. Assegna il token Modifiche successivo come nuovo token.
4. Ripeti i passaggi 1-3 finché non ci sono più Modifiche.
5. Memorizza 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 l'estrazione dei dati, consulta le best practice per Sincronizza i dati.

Elabora le modifiche ai dati

Riflettono le modifiche al data store dell'app. Per UpsertionChange, utilizza id e lastModifiedTime dal relativo metadata per eseguire l'upsert del 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 di getChanges o assicurarti di avere memorizzato queste informazioni separatamente in precedenza.

Eliminare i dati da Connessione Salute

Quando un utente elimina i propri dati dalla tua app, assicurati che vengano anche rimossi da Connessione Salute. A questo scopo, usa deleteRecords. Richiede un tipo di record e un elenco di valori id e clientRecordId, il che rende pratico raggruppare più dati per l'eliminazione. È disponibile anche un'alternativa deleteRecords che accetta un timeRangeFilter.

Best practice per la sincronizzazione dei dati

I seguenti fattori influiscono sulla procedura di sincronizzazione.

Scadenza del token

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

• Cerca nel tuo datastore dell'app il record utilizzato più di recente che abbia anche un id di Connessione Salute.
• Richiedi i record di Connessione Salute che iniziano con un timestamp specifico, quindi inseriscili o aggiornali nel data store della tua app.
• Richiedi un token di modifiche per prenotarlo per la prossima volta che sarà necessario.

Strategie di gestione delle modifiche consigliate

Se la tua app riceve token Changes non validi o scaduti, ti consigliamo le seguenti strategie di gestione a seconda della loro applicazione nella tua logica:

• Leggi e deduplica tutti i dati. Questa è la strategia più ideale.
  • Memorizzare il timestamp dell'ultima volta che ha letto i dati da Connessione Salute.
  • Alla scadenza del token, rileggi tutti i dati dal timestamp più recente o per gli ultimi 30 giorni. Poi, elimina le duplicazioni rispetto ai dati letti in precedenza utilizzando gli identificativi.
  • Idealmente, implementa gli ID client, poiché sono necessari per gli aggiornamenti dei dati.
• Leggi solo i dati dal timestamp dell'ultima lettura. Ciò comporta alcune discrepanze nei dati al momento dell'espirazione del token di modifica, ma il periodo di tempo è più breve e può richiedere da alcune ore a un paio di giorni.
  • Memorizzare il timestamp dell'ultima volta che ha letto i dati da Connessione Salute.
  • Alla scadenza del token, leggi tutti i dati a partire da questo timestamp.
• Elimina e poi leggi i dati degli ultimi 30 giorni. Questo è più in linea con quanto accade alla prima integrazione.
  • Eliminare tutti i dati letti dall'app da Connessione Salute negli ultimi 30 giorni.
  • Una volta eliminati, leggi di nuovo tutti questi dati.
• Leggi i dati degli ultimi 30 giorni senza eliminazione delle duplicazioni. Si tratta della strategia meno ideale e comporta la visualizzazione di dati duplicati per gli utenti.
  • Eliminare tutti i dati letti dall'app da Connessione Salute per gli ultimi 30 giorni.
  • Consenti voci duplicate.

Token di modifica del tipo di dati

Se la tua app utilizza più di un tipo di dati in modo indipendente, utilizza token di modifica distinti 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 per niente.

Letture in primo piano

Le app possono leggere i dati di Connessione Salute solo quando sono in primo piano. Durante la sincronizzazione dei 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 continuare la prossima volta che viene aperta.

Letture in background

Puoi richiedere che la tua applicazione venga eseguita in background e legga i dati da Connessione Salute. Se richiedi l'autorizzazione Background Read, l'utente può concedere alla tua app l'accesso in background per leggere i dati.

Importa tempistiche

Poiché la tua app non può ricevere notifiche di nuovi dati, controlla se sono disponibili nuovi dati in due momenti:

• 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. Invia una notifica agli utenti quando sono disponibili nuovi dati, in modo che possano aggiornare la schermata in base alle modifiche.