Cette page a été traduite par l'API Cloud Translation.

Synchroniser les données

La plupart des applications qui s'intègrent à Santé Connect ont leur propre datastore qui sert de source de référence. Santé Connect offre divers moyens de synchroniser votre application.

Vérifiez que votre application effectue les opérations suivantes :

Elle transfère les données nouvelles ou mises à jour du datastore de votre application vers Santé Connect.
Elle extrait les modifications de données de Santé Connect, qui sont répercutées dans le datastore de votre application.
Elle élimine les données de Santé Connect lorsqu'elles sont supprimées du datastore de votre application.

Dans chaque cas, assurez-vous que le processus de synchronisation maintient la cohérence entre Santé Connect et le datastore de votre application.

Transmettre les données à Santé Connect

La première partie du processus de synchronisation consiste à transmettre les données du datastore de votre application au datastore Santé Connect.

Préparer vos données

En règle générale, les enregistrements du datastore de votre application présentent les détails suivants :

Une clé unique, comme un UUID
Une version ou un horodatage

Concevez le datastore de votre application de sorte qu'il consigne les données qui ont déjà été transmises à Santé Connect. Pour ce faire, appliquez la logique suivante :

Fournissez la liste des modifications et un jeton permettant de récupérer les enregistrements ayant été mis à jour depuis l'émission du dernier jeton.
Effectuez le suivi de la dernière fois où des données exportées ont été modifiées.

Ces étapes sont essentielles pour garantir que seules les données nouvelles ou mises à jour sont transmises à Santé Connect.

Écrire des données dans Santé Connect

Pour fournir des données à Santé Connect, procédez comme suit :

Générez une liste des entrées nouvelles ou mises à jour dans le datastore de votre application.
Pour chaque entrée, créez un objet Record adapté à ce type de données. Par exemple, créez un objet WeightRecord pour les données liées au poids.
Spécifiez un objet Metadata pour chaque Record à l'aide de la clé unique et des informations de version issus du datastore de votre application. Si vos données ne sont pas gérées par version, vous pouvez utiliser la valeur Long de l'horodatage actuel comme alternative.
```
val record = WeightRecord(
    metadata = Metadata(
        clientRecordId = "<Your record's Client ID>",
        clientRecordVersion = <Your record's version>
    ),
    weight = weight,
    time = time,
    zoneOffset = zoneOffset
)
```
Insérez des données dans Santé Connect à l'aide d'insertRecords. Lors de l'insertion, toutes les données existantes de Santé Connect sont écrasées tant que les valeurs clientRecordId existent dans le datastore de Santé Connect et que la clientRecordVersion est supérieure à la valeur existante. Sinon, les données insérées sont écrites en tant que nouvelles données.
```
healthConnectClient.insertRecords(arrayListOf(record))
```

Pour en savoir plus sur les considérations pratiques spécifiques à l'insertion de données, consultez les bonnes pratiques d'écriture de données.

Stocker les ID Santé Connect

Après avoir vérifié vos enregistrements dans Santé Connect, le datastore de votre application doit stocker l'id Santé Connect de chaque enregistrement. Cela permet à votre application de vérifier si chaque modification entrante nécessite la création ou la mise à jour d'un enregistrement après l'extraction des données.

La fonction insertRecords renvoie une InsertRecordsResponse contenant la liste des valeurs id. Utilisez cette réponse pour obtenir les ID d'enregistrement et les stocker.

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

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

Extraire des données de Santé Connect

La deuxième partie du processus de synchronisation consiste à extraire les modifications de données de Santé Connect vers le datastore de votre application. Les modifications de données comprennent les mises à jour et les suppressions.

Obtenir un jeton de modifications

Pour obtenir la liste des modifications à extraire de Santé Connect, votre application doit suivre les jetons de modifications. Ils sont utiles lorsque vous demandez à recevoir à la fois une liste des modifications de données et un nouveau jeton de modifications pour la prochaine fois.

Pour obtenir un jeton de modifications, appelez getChangesToken et fournissez les types de données requis.

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

Vérifier les modifications de données

Maintenant que vous avez obtenu un jeton de modifications, utilisez-le pour obtenir toutes les modifications. Nous vous recommandons de créer une boucle pour passer en revue toutes les modifications et vérifier ainsi s'il existe des modifications de données disponibles. Procédez comme suit :

Appelez getChanges à l'aide du jeton pour obtenir la liste des modifications.
Vérifiez chaque modification, qu'il s'agisse d'un objet UpsertionChange ou DeletionChange, puis effectuez les opérations nécessaires.
- Pour UpsertionChange, n'acceptez que les modifications qui ne proviennent pas de l'application appelante pour vous assurer de ne pas réimporter les données.
Attribuez le jeton de modifications suivant comme nouveau jeton.
Répétez les étapes 1 à 3 jusqu'à ce qu'il ne reste plus aucune modification.
Stockez le jeton suivant et réservez-le pour une importation ultérieure.

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
}

Pour en savoir plus sur les considérations pratiques liées à l'extraction de données, consultez les bonnes pratiques de synchronisation des données.

Traiter les modifications des données

Reflétez les modifications apportées au datastore de votre application. Pour UpsertionChange, utilisez l'id et l'élément lastModifiedTime à partir de ses metadata pour insérer l'enregistrement. Pour DeletionChange, utilisez l'id fourni pour supprimer l'enregistrement.

Supprimer des données de Santé Connect

Lorsqu'un utilisateur supprime ses propres données de votre application, assurez-vous qu'elles sont également supprimées de Santé Connect. Pour ce faire, utilisez deleteRecords. Elle utilise un type d'enregistrement et une liste de valeurs id et clientRecordId, ce qui facilite le traitement par lot de plusieurs données à supprimer. Une autre deleteRecords qui accepte un timeRangeFilter est également disponible.

Bonnes pratiques pour la synchronisation des données

Les facteurs suivants ont un impact sur le processus de synchronisation.

Expiration des jetons

Étant donné qu'un jeton de modifications inutilisé expire dans les 30 jours, vous devez adopter une stratégie de synchronisation qui évite de perdre des informations dans ce cas. Votre stratégie peut inclure les approches suivantes :

Dans le datastore de votre application, recherchez le dernier enregistrement consommé également associé à un id Santé Connect.
Demandez à Santé Connect les enregistrements qui commencent par un code temporel spécifique, puis insérez-les ou mettez-les à jour dans le datastore de votre application.
Demandez un jeton de modifications afin de le réserver pour la prochaine fois que vous en aurez besoin.

Stratégies recommandées de gestion des modifications

Si votre application reçoit des jetons de modifications non valides ou ayant expiré, nous vous recommandons les stratégies de gestion suivantes en fonction de son application dans votre logique :

Lire et dédupliquer toutes les données : il s'agit de la stratégie la plus adaptée.
- Stockez le code temporel indiquant la dernière fois que les données de Santé Connect ont été lues.
- À l'expiration du jeton, relisez toutes les données du dernier code temporel ou des 30 derniers jours. Dédupliquez-les ensuite par rapport aux données lues précédemment à l'aide d'identifiants.
- Idéalement, implémentez des ID client, car ils sont requis pour les mises à jour de données.
Lire uniquement les données depuis le code temporel où elles ont été lues pour la dernière fois : cette stratégie entraîne des écarts de données à l'expiration de votre jeton de modifications, mais cette période plus courte peut prendre de quelques heures à quelques jours.
- Stockez le code temporel indiquant la dernière fois que les données de Santé Connect ont été lues.
- À l'expiration du jeton, lisez toutes les données à partir de ce code temporel.
Supprimer, puis lire les données des 30 derniers jours : cette stratégie correspond plus précisément à ce qui se passe lors de la première intégration.
- Supprimez de Santé Connect toutes les données lues par l'application au cours des 30 derniers jours.
- Une fois les données supprimées, lisez-les de nouveau.
Lire les données des 30 derniers jours sans déduplication : il s'agit de la stratégie la moins conseillée, car elle entraîne l'affichage de données en double pour les utilisateurs.
- Supprimez de Santé Connect toutes les données lues par l'application au cours des 30 derniers jours.
- Autorisez les entrées en double.

Jetons de modifications par type de données

Si votre application consomme plusieurs types de données indépendamment, utilisez des jetons de modification distincts pour chaque type de données. N'utilisez une liste de plusieurs types de données avec l'API Changes Sync que si ces types de données sont soit toujours consommés ensemble, soit jamais consommés ensemble.

Lectures au premier plan

Les applications ne peuvent lire les données de Santé Connect que lorsqu'elles sont au premier plan. Lorsque vous synchronisez des données à partir de Santé Connect, l'accès à Santé Connect peut être interrompu à tout moment. Par exemple, lorsqu'elle lit une grande quantité de données à partir de Santé Connect, votre application doit gérer les interruptions qui ont lieu en cours de synchronisation et reprendre la prochaine fois que l'application sera ouverte.

Planification des importations

Comme votre application ne peut pas recevoir de notifications en cas de nouvelles données, elle doit les rechercher dans les deux cas de figure suivants.

Chaque fois que votre application devient active au premier plan. Dans ce cas, utilisez des événements de cycle de vie.
À intervalles réguliers, pendant que votre application reste au premier plan. Informez les utilisateurs lorsque de nouvelles données sont disponibles, ce qui leur permettra d'actualiser leur écran en conséquence.