Activer les fonctionnalités hors connexion sur Android

Les applications Firebase fonctionnent même si votre application perd temporairement sa connexion réseau. De plus, Firebase fournit des outils permettant de conserver des données localement, de gérer la présence et de gérer la latence.

Persistance de disque

Les applications Firebase gèrent automatiquement les interruptions réseau temporaires. Les données mises en cache sont disponibles hors connexion, et Firebase renvoie toutes les écritures lorsque la connectivité réseau est rétablie.

Lorsque vous activez la persistance sur disque, votre application écrit les données localement sur l'appareil afin de pouvoir conserver son état hors connexion, même si l'utilisateur ou le système d'exploitation redémarre l'application.

Vous pouvez activer la persistance de disque en une seule ligne de code.

Kotlin+KTX

Firebase.database.setPersistenceEnabled(true)
OfflineActivity.kt

Java

FirebaseDatabase.getInstance().setPersistenceEnabled(true);
OfflineActivity.java

Comportement de persistance

En activant la persistance, toutes les données que le client Firebase Realtime Database synchroniserait en ligne sont conservées sur le disque et sont disponibles hors connexion, même lorsque l'utilisateur ou le système d'exploitation redémarre l'application. Cela signifie que votre application fonctionne comme elle le ferait en ligne en utilisant les données locales stockées dans le cache. Les rappels d'écouteur continueront de se déclencher pour les mises à jour locales.

Le client Firebase Realtime Database conserve automatiquement une file d'attente de toutes les opérations d'écriture effectuées lorsque votre application est hors connexion. Lorsque la persistance est activée, cette file d'attente est également conservée sur le disque afin que toutes vos écritures soient disponibles lorsque l'utilisateur ou le système d'exploitation redémarre l'application. Lorsque l'application récupère la connectivité, toutes les opérations sont envoyées au serveur Firebase Realtime Database.

Si votre application utilise Firebase Authentication, le client Firebase Realtime Database conserve le jeton d'authentification de l'utilisateur lors des redémarrages de l'application. Si le jeton d'authentification expire alors que votre application est hors connexion, le client met en pause les opérations d'écriture jusqu'à ce que votre application réauthentifie l'utilisateur. Sinon, les opérations d'écriture risquent d'échouer en raison de règles de sécurité.

Actualiser les données

Firebase Realtime Database synchronise et stocke une copie locale des données pour les écouteurs actifs. De plus, vous pouvez synchroniser des établissements spécifiques.

Kotlin+KTX

val scoresRef = Firebase.database.getReference("scores")
scoresRef.keepSynced(true)
OfflineActivity.kt

Java

DatabaseReference scoresRef = FirebaseDatabase.getInstance().getReference("scores");
scoresRef.keepSynced(true);
OfflineActivity.java

Le client Firebase Realtime Database télécharge automatiquement les données à ces emplacements et les synchronise même si la référence n'a aucun écouteur actif. Vous pouvez désactiver à nouveau la synchronisation à l'aide de la ligne de code suivante.

Kotlin+KTX

scoresRef.keepSynced(false)
OfflineActivity.kt

Java

scoresRef.keepSynced(false);
OfflineActivity.java

Par défaut, 10 Mo de données précédemment synchronisées sont mis en cache. Cela devrait être suffisant pour la plupart des applications. Si le cache dépasse la taille configurée, Firebase Realtime Database supprime définitivement les données qui ont été utilisées le moins récemment. Les données synchronisées ne sont pas supprimées du cache.

Interroger des données hors connexion

Firebase Realtime Database stocke les données renvoyées par une requête pour les utiliser hors connexion. Pour les requêtes créées hors connexion, Firebase Realtime Database continue de fonctionner pour les données précédemment chargées. Si les données demandées ne sont pas chargées, Firebase Realtime Database charge les données à partir du cache local. Lorsque la connectivité réseau est à nouveau disponible, les données se chargent et reflètent la requête.

Par exemple, ce code interroge les quatre derniers éléments d'un Firebase Realtime Database de scores.

Kotlin+KTX

val scoresRef = Firebase.database.getReference("scores")
scoresRef.orderByValue().limitToLast(4).addChildEventListener(object : ChildEventListener {
    override fun onChildAdded(snapshot: DataSnapshot, previousChild: String?) {
        Log.d(TAG, "The ${snapshot.key} dinosaur's score is ${snapshot.value}")
    }

    // ...
})
OfflineActivity.kt

Java

DatabaseReference scoresRef = FirebaseDatabase.getInstance().getReference("scores");
scoresRef.orderByValue().limitToLast(4).addChildEventListener(new ChildEventListener() {
    @Override
    public void onChildAdded(@NonNull DataSnapshot snapshot, String previousChild) {
        Log.d(TAG, "The " + snapshot.getKey() + " dinosaur's score is " + snapshot.getValue());
    }

    // ...
});
OfflineActivity.java

Supposons que l'utilisateur perd la connexion, passe hors connexion et redémarre l'application. Lorsqu'elle est toujours hors connexion, l'application interroge les deux derniers éléments depuis le même emplacement. Cette requête renverra les deux derniers éléments, car l'application a chargé les quatre éléments de la requête ci-dessus.

Kotlin+KTX

scoresRef.orderByValue().limitToLast(2).addChildEventListener(object : ChildEventListener {
    override fun onChildAdded(snapshot: DataSnapshot, previousChild: String?) {
        Log.d(TAG, "The ${snapshot.key} dinosaur's score is ${snapshot.value}")
    }

    // ...
})
OfflineActivity.kt

Java

scoresRef.orderByValue().limitToLast(2).addChildEventListener(new ChildEventListener() {
    @Override
    public void onChildAdded(@NonNull DataSnapshot snapshot, String previousChild) {
        Log.d(TAG, "The " + snapshot.getKey() + " dinosaur's score is " + snapshot.getValue());
    }

    // ...
});
OfflineActivity.java

Dans l'exemple précédent, le client Firebase Realtime Database génère des événements "enfant ajouté" pour les deux dinosaures les plus performants, à l'aide du cache persistant. Toutefois, il ne déclenchera pas d'événement "value", car l'application n'a jamais exécuté cette requête en ligne.

Si l'application demandait les six derniers éléments en mode hors connexion, elle recevrait immédiatement des événements "enfant ajouté" pour les quatre éléments mis en cache. Lorsque l'appareil revient en ligne, le client Firebase Realtime Database se synchronise avec le serveur et obtient les deux derniers événements "child added" et "value" pour l'application.

Gérer les transactions hors connexion

Toutes les transactions effectuées lorsque l'application est hors connexion sont mises en file d'attente. Une fois que l'application a rétabli la connectivité réseau, les transactions sont envoyées au serveur Realtime Database.

Les transactions ne sont pas conservées lors des redémarrages de l'application.

Même si la persistance est activée, les transactions ne sont pas conservées lors des redémarrages de l'application. Vous ne pouvez donc pas vous fier aux transactions effectuées hors connexion pour enregistrer votre Firebase Realtime Database. Pour offrir une expérience utilisateur optimale, votre application doit indiquer qu'une transaction n'a pas encore été enregistrée dans votre Firebase Realtime Database, ou vous assurer qu'elle les mémorise manuellement et les exécute à nouveau après un redémarrage de l'application.

La Firebase Realtime Database dispose de nombreuses fonctionnalités pour gérer les scénarios hors connexion et la connectivité réseau. Le reste de ce guide s'applique à votre application, que la persistance soit activée ou non.

Gérer la présence

Dans les applications en temps réel, il est souvent utile de détecter quand les clients se connectent et se déconnectent. Par exemple, vous pouvez marquer un utilisateur comme "hors connexion" lorsque son client se déconnecte.

Les clients Firebase Database fournissent des primitives simples que vous pouvez utiliser pour écrire dans la base de données lorsqu'un client se déconnecte des serveurs Firebase Database. Ces mises à jour se produisent que le client se déconnecte de manière propre ou non. Vous pouvez donc vous y fier pour nettoyer les données même si une connexion est interrompue ou si un client plante. Toutes les opérations d'écriture, y compris la définition, la mise à jour et la suppression, peuvent être effectuées lors d'une déconnexion.

Voici un exemple simple d'écriture de données lors de la déconnexion à l'aide de la primitive onDisconnect :

Kotlin+KTX

val presenceRef = Firebase.database.getReference("disconnectmessage")
// Write a string when this client loses connection
presenceRef.onDisconnect().setValue("I disconnected!")
OfflineActivity.kt

Java

DatabaseReference presenceRef = FirebaseDatabase.getInstance().getReference("disconnectmessage");
// Write a string when this client loses connection
presenceRef.onDisconnect().setValue("I disconnected!");
OfflineActivity.java

Fonctionnement de onDisconnect

Lorsque vous établissez une opération onDisconnect(), celle-ci se trouve sur le serveur Firebase Realtime Database. Le serveur vérifie la sécurité pour s'assurer que l'utilisateur peut effectuer l'événement d'écriture demandé et informe votre application s'il n'est pas valide. Le serveur surveille ensuite la connexion. Si la connexion expire à un moment donné ou est fermée activement par le client Realtime Database, le serveur vérifie la sécurité une seconde fois (pour s'assurer que l'opération est toujours valide), puis appelle l'événement.

Votre application peut utiliser le rappel de l'opération d'écriture pour s'assurer que onDisconnect a été correctement associé :

Kotlin+KTX

presenceRef.onDisconnect().removeValue { error, reference ->
    error?.let {
        Log.d(TAG, "could not establish onDisconnect event: ${error.message}")
    }
}
OfflineActivity.kt

Java

presenceRef.onDisconnect().removeValue(new DatabaseReference.CompletionListener() {
    @Override
    public void onComplete(DatabaseError error, @NonNull DatabaseReference reference) {
        if (error != null) {
            Log.d(TAG, "could not establish onDisconnect event:" + error.getMessage());
        }
    }
});
OfflineActivity.java

Un événement onDisconnect peut également être annulé en appelant .cancel():

Kotlin+KTX

val onDisconnectRef = presenceRef.onDisconnect()
onDisconnectRef.setValue("I disconnected")
// ...
// some time later when we change our minds
// ...
onDisconnectRef.cancel()
OfflineActivity.kt

Java

OnDisconnect onDisconnectRef = presenceRef.onDisconnect();
onDisconnectRef.setValue("I disconnected");
// ...
// some time later when we change our minds
// ...
onDisconnectRef.cancel();
OfflineActivity.java

Détecter l'état de la connexion

Pour de nombreuses fonctionnalités liées à la présence, il est utile que votre application sache quand elle est en ligne ou hors connexion. Firebase Realtime Database fournit un emplacement spécial à /.info/connected, qui est mis à jour chaque fois que l'état de connexion du client Firebase Realtime Database change. Voici un exemple :

Kotlin+KTX

val connectedRef = Firebase.database.getReference(".info/connected")
connectedRef.addValueEventListener(object : ValueEventListener {
    override fun onDataChange(snapshot: DataSnapshot) {
        val connected = snapshot.getValue(Boolean::class.java) ?: false
        if (connected) {
            Log.d(TAG, "connected")
        } else {
            Log.d(TAG, "not connected")
        }
    }

    override fun onCancelled(error: DatabaseError) {
        Log.w(TAG, "Listener was cancelled")
    }
})
OfflineActivity.kt

Java

DatabaseReference connectedRef = FirebaseDatabase.getInstance().getReference(".info/connected");
connectedRef.addValueEventListener(new ValueEventListener() {
    @Override
    public void onDataChange(@NonNull DataSnapshot snapshot) {
        boolean connected = snapshot.getValue(Boolean.class);
        if (connected) {
            Log.d(TAG, "connected");
        } else {
            Log.d(TAG, "not connected");
        }
    }

    @Override
    public void onCancelled(@NonNull DatabaseError error) {
        Log.w(TAG, "Listener was cancelled");
    }
});
OfflineActivity.java

/.info/connected est une valeur booléenne qui n'est pas synchronisée entre les clients Realtime Database, car la valeur dépend de l'état du client. En d'autres termes, si un client lit /.info/connected comme étant "false", cela ne garantit pas qu'un client distinct lira également la valeur "false".

Sur Android, Firebase gère automatiquement l'état de la connexion pour réduire l'utilisation de la bande passante et de la batterie. Lorsqu'un client n'a pas d'écouteurs actifs, aucune opération d'écriture ou onDisconnect en attente et qu'il n'est pas explicitement déconnecté par la méthode goOffline, Firebase ferme la connexion au bout de 60 secondes d'inactivité.

Gérer la latence

Code temporel du serveur

Les serveurs Firebase Realtime Database fournissent un mécanisme permettant d'insérer les horodatages générés sur le serveur en tant que données. Cette fonctionnalité, combinée à onDisconnect, permet de noter de manière fiable l'heure à laquelle un client Realtime Database s'est déconnecté:

Kotlin+KTX

val userLastOnlineRef = Firebase.database.getReference("users/joe/lastOnline")
userLastOnlineRef.onDisconnect().setValue(ServerValue.TIMESTAMP)
OfflineActivity.kt

Java

DatabaseReference userLastOnlineRef = FirebaseDatabase.getInstance().getReference("users/joe/lastOnline");
userLastOnlineRef.onDisconnect().setValue(ServerValue.TIMESTAMP);
OfflineActivity.java

Décalage de l'horloge

Bien que firebase.database.ServerValue.TIMESTAMP soit beaucoup plus précis et préférable pour la plupart des opérations de lecture/écriture, il peut parfois être utile d'estimer le décalage de l'horloge du client par rapport aux serveurs de Firebase Realtime Database. Vous pouvez associer un rappel à l'emplacement /.info/serverTimeOffset pour obtenir la valeur, en millisecondes, que les clients Firebase Realtime Database ajoutent à l'heure locale signalée (heure de l'epoch en millisecondes) pour estimer l'heure du serveur. Notez que la précision de ce décalage peut être affectée par la latence réseau. Il est donc principalement utile pour détecter les écarts importants (> 1 seconde) dans l'heure de l'horloge.

Kotlin+KTX

val offsetRef = Firebase.database.getReference(".info/serverTimeOffset")
offsetRef.addValueEventListener(object : ValueEventListener {
    override fun onDataChange(snapshot: DataSnapshot) {
        val offset = snapshot.getValue(Double::class.java) ?: 0.0
        val estimatedServerTimeMs = System.currentTimeMillis() + offset
    }

    override fun onCancelled(error: DatabaseError) {
        Log.w(TAG, "Listener was cancelled")
    }
})
OfflineActivity.kt

Java

DatabaseReference offsetRef = FirebaseDatabase.getInstance().getReference(".info/serverTimeOffset");
offsetRef.addValueEventListener(new ValueEventListener() {
    @Override
    public void onDataChange(@NonNull DataSnapshot snapshot) {
        double offset = snapshot.getValue(Double.class);
        double estimatedServerTimeMs = System.currentTimeMillis() + offset;
    }

    @Override
    public void onCancelled(@NonNull DatabaseError error) {
        Log.w(TAG, "Listener was cancelled");
    }
});
OfflineActivity.java

Exemple d'application Presence

En combinant les opérations de déconnexion à la surveillance de l'état de la connexion et aux codes temporels du serveur, vous pouvez créer un système de présence des utilisateurs. Dans ce système, chaque utilisateur stocke des données à un emplacement de base de données pour indiquer si un client Realtime Database est en ligne ou non. Les clients définissent cette position sur "True" lorsqu'ils se connectent et sur un code temporel lorsqu'ils se déconnectent. Ce code temporel indique la dernière fois que l'utilisateur donné était en ligne.

Notez que votre application doit mettre en file d'attente les opérations de déconnexion avant qu'un utilisateur ne soit marqué en ligne, afin d'éviter toute condition de course si la connexion réseau du client est perdue avant que les deux commandes ne puissent être envoyées au serveur.

Voici un système de présence utilisateur simple :

Kotlin+KTX

// Since I can connect from multiple devices, we store each connection instance separately
// any time that connectionsRef's value is null (i.e. has no children) I am offline
val database = Firebase.database
val myConnectionsRef = database.getReference("users/joe/connections")

// Stores the timestamp of my last disconnect (the last time I was seen online)
val lastOnlineRef = database.getReference("/users/joe/lastOnline")

val connectedRef = database.getReference(".info/connected")
connectedRef.addValueEventListener(object : ValueEventListener {
    override fun onDataChange(snapshot: DataSnapshot) {
        val connected = snapshot.getValue<Boolean>() ?: false
        if (connected) {
            val con = myConnectionsRef.push()

            // When this device disconnects, remove it
            con.onDisconnect().removeValue()

            // When I disconnect, update the last time I was seen online
            lastOnlineRef.onDisconnect().setValue(ServerValue.TIMESTAMP)

            // Add this device to my connections list
            // this value could contain info about the device or a timestamp too
            con.setValue(java.lang.Boolean.TRUE)
        }
    }

    override fun onCancelled(error: DatabaseError) {
        Log.w(TAG, "Listener was cancelled at .info/connected")
    }
})
OfflineActivity.kt

Java

// Since I can connect from multiple devices, we store each connection instance separately
// any time that connectionsRef's value is null (i.e. has no children) I am offline
final FirebaseDatabase database = FirebaseDatabase.getInstance();
final DatabaseReference myConnectionsRef = database.getReference("users/joe/connections");

// Stores the timestamp of my last disconnect (the last time I was seen online)
final DatabaseReference lastOnlineRef = database.getReference("/users/joe/lastOnline");

final DatabaseReference connectedRef = database.getReference(".info/connected");
connectedRef.addValueEventListener(new ValueEventListener() {
    @Override
    public void onDataChange(@NonNull DataSnapshot snapshot) {
        boolean connected = snapshot.getValue(Boolean.class);
        if (connected) {
            DatabaseReference con = myConnectionsRef.push();

            // When this device disconnects, remove it
            con.onDisconnect().removeValue();

            // When I disconnect, update the last time I was seen online
            lastOnlineRef.onDisconnect().setValue(ServerValue.TIMESTAMP);

            // Add this device to my connections list
            // this value could contain info about the device or a timestamp too
            con.setValue(Boolean.TRUE);
        }
    }

    @Override
    public void onCancelled(@NonNull DatabaseError error) {
        Log.w(TAG, "Listener was cancelled at .info/connected");
    }
});
OfflineActivity.java