Accéder aux données hors ligne

Cloud Firestore prend en charge la persistance des données hors ligne. Cette fonctionnalité met en cache une copie des données Cloud Firestore que votre application utilise activement, afin que votre application puisse accéder aux données lorsque l'appareil est hors ligne. Vous pouvez écrire, lire, écouter et interroger les données mises en cache. Lorsque l'appareil revient en ligne, Cloud Firestore synchronise toutes les modifications locales apportées par votre application avec le backend Cloud Firestore.

Pour utiliser la persistance hors ligne, vous n'avez pas besoin de modifier le code que vous utilisez pour accéder aux données Cloud Firestore. Lorsque la persistance hors ligne est activée, la bibliothèque client Cloud Firestore gère automatiquement l'accès aux données en ligne et hors ligne et synchronise les données locales lorsque l'appareil est de nouveau en ligne.

Configurer la persistance hors ligne

Lorsque vous initialisez Cloud Firestore, vous pouvez activer ou désactiver la persistance hors ligne :

  • Pour les plateformes Android et Apple, la persistance hors ligne est activée par défaut. Pour désactiver la persistance, définissez l'option PersistenceEnabled sur false .
  • Pour le Web, la persistance hors ligne est désactivée par défaut. Pour activer la persistance, appelez la méthode enablePersistence . Le cache de Cloud Firestore n'est pas automatiquement vidé entre les sessions. Par conséquent, si votre application Web gère des informations sensibles, assurez-vous de demander à l'utilisateur s'il se trouve sur un appareil de confiance avant d'activer la persistance.

Web modular API

// Memory cache is the default if no config is specified.
initializeFirestore(app);

// This is the default behavior if no persistence is specified.
initializeFirestore(app, {localCache: memoryLocalCache()});

// Defaults to single-tab persistence if no tab manager is specified.
initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})});

// Same as `initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})})`,
// but more explicit about tab management.
initializeFirestore(app, 
  {localCache: 
    persistentLocalCache(/*settings*/{tabManager: persistentSingleTabManager()})
});

// Use multi-tab IndexedDb persistence.
initializeFirestore(app, 
  {localCache: 
    persistentLocalCache(/*settings*/{tabManager: persistentMultipleTabManager()})
  });
  

Web namespaced API

firebase.firestore().enablePersistence()
  .catch((err) => {
      if (err.code == 'failed-precondition') {
          // Multiple tabs open, persistence can only be enabled
          // in one tab at a a time.
          // ...
      } else if (err.code == 'unimplemented') {
          // The current browser does not support all of the
          // features required to enable persistence
          // ...
      }
  });
// Subsequent queries will use persistence, if it was enabled successfully
Rapide
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
let settings = FirestoreSettings()

// Use memory-only cache
settings.cacheSettings =
MemoryCacheSettings(garbageCollectorSettings: MemoryLRUGCSettings())

// Use persistent disk cache, with 100 MB cache size
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber)

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
Objectif c
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];

// Use memory-only cache
settings.cacheSettings = [[FIRMemoryCacheSettings alloc]
    initWithGarbageCollectorSettings:[[FIRMemoryLRUGCSettings alloc] init]];

// Use persistent disk cache (default behavior)
// This example uses 100 MB.
settings.cacheSettings = [[FIRPersistentCacheSettings alloc]
    initWithSizeBytes:@(100 * 1024 * 1024)];

// Any additional options
// ...

// Enable offline data persistence
FIRFirestore *db = [FIRFirestore firestore];
db.settings = settings;

Kotlin+KTX

val settings = firestoreSettings {
    // Use memory cache
    setLocalCacheSettings(memoryCacheSettings {})
    // Use persistent disk cache (default)
    setLocalCacheSettings(persistentCacheSettings {})
}
db.firestoreSettings = settings

Java

FirebaseFirestoreSettings settings = 
new FirebaseFirestoreSettings.Builder(db.getFirestoreSettings())
    // Use memory-only cache
    .setLocalCacheSettings(MemoryCacheSettings.newBuilder().build())
    // Use persistent disk cache (default)
    .setLocalCacheSettings(PersistentCacheSettings.newBuilder()
                            .build())
    .build();
db.setFirestoreSettings(settings);

Dart

// Apple and Android
db.settings = const Settings(persistenceEnabled: true);

// Web
await db
    .enablePersistence(const PersistenceSettings(synchronizeTabs: true));

Configurer la taille du cache

Lorsque la persistance est activée, Cloud Firestore met en cache chaque document reçu du backend pour un accès hors ligne. Cloud Firestore définit un seuil par défaut pour la taille du cache. Après avoir dépassé la valeur par défaut, Cloud Firestore tente périodiquement de nettoyer les documents plus anciens et inutilisés. Vous pouvez configurer un seuil de taille de cache différent ou désactiver complètement le processus de nettoyage :

Web modular API

import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";

const firestoreDb = initializeFirestore(app, {
  cacheSizeBytes: CACHE_SIZE_UNLIMITED
});

Web namespaced API

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
Rapide
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "FirestoreCacheSizeUnlimited"
// to disable clean-up.
let settings = Firestore.firestore().settings
// Set cache size to 100 MB
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber)
Firestore.firestore().settings = settings
Objectif c
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "kFIRFirestoreCacheSizeUnlimited"
// to disable clean-up.
FIRFirestoreSettings *settings = [FIRFirestore firestore].settings;
// Set cache size to 100 MB
settings.cacheSettings =
    [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)];
[FIRFirestore firestore].settings = settings;
  

Kotlin+KTX


// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
val settings = FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build()
db.firestoreSettings = settings

Java


// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build();
db.setFirestoreSettings(settings);

Dart

db.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);

Écoutez des données hors ligne

Lorsque l'appareil est hors ligne, si vous avez activé la persistance hors ligne, vos écouteurs recevront des événements d'écoute lorsque les données mises en cache localement changeront. Vous pouvez écouter des documents, des collections et des requêtes.

Pour vérifier si vous recevez des données du serveur ou du cache, utilisez la propriété fromCache sur SnapshotMetadata dans votre événement d'instantané. Si fromCache est true , les données proviennent du cache et peuvent être périmées ou incomplètes. Si fromCache est false , les données sont complètes et à jour avec les dernières mises à jour sur le serveur.

Par défaut, aucun événement n'est déclenché si seules les SnapshotMetadata ont été modifiées. Si vous comptez sur les valeurs fromCache , spécifiez l'option d'écoute includeMetadataChanges lorsque vous attachez votre gestionnaire d'écoute.

Web modular API

import { collection, onSnapshot, where, query } from "firebase/firestore"; 

const q = query(collection(db, "cities"), where("state", "==", "CA"));
onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
    snapshot.docChanges().forEach((change) => {
        if (change.type === "added") {
            console.log("New city: ", change.doc.data());
        }

        const source = snapshot.metadata.fromCache ? "local cache" : "server";
        console.log("Data came from " + source);
    });
});

Web namespaced API

db.collection("cities").where("state", "==", "CA")
  .onSnapshot({ includeMetadataChanges: true }, (snapshot) => {
      snapshot.docChanges().forEach((change) => {
          if (change.type === "added") {
              console.log("New city: ", change.doc.data());
          }

          var source = snapshot.metadata.fromCache ? "local cache" : "server";
          console.log("Data came from " + source);
      });
  });
Rapide
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
db.collection("cities").whereField("state", isEqualTo: "CA")
  .addSnapshotListener(includeMetadataChanges: true) { querySnapshot, error in
    guard let snapshot = querySnapshot else {
      print("Error retreiving snapshot: \(error!)")
      return
    }

    for diff in snapshot.documentChanges {
      if diff.type == .added {
        print("New city: \(diff.document.data())")
      }
    }

    let source = snapshot.metadata.isFromCache ? "local cache" : "server"
    print("Metadata: Data fetched from \(source)")
  }
Objectif c
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
[[[db collectionWithPath:@"cities"] queryWhereField:@"state" isEqualTo:@"CA"]
    addSnapshotListenerWithIncludeMetadataChanges:YES
    listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
      if (snapshot == nil) {
        NSLog(@"Error retreiving snapshot: %@", error);
        return;
      }
      for (FIRDocumentChange *diff in snapshot.documentChanges) {
        if (diff.type == FIRDocumentChangeTypeAdded) {
          NSLog(@"New city: %@", diff.document.data);
        }
      }

      NSString *source = snapshot.metadata.isFromCache ? @"local cache" : @"server";
      NSLog(@"Metadata: Data fetched from %@", source);
    }];

Kotlin+KTX

db.collection("cities").whereEqualTo("state", "CA")
    .addSnapshotListener(MetadataChanges.INCLUDE) { querySnapshot, e ->
        if (e != null) {
            Log.w(TAG, "Listen error", e)
            return@addSnapshotListener
        }

        for (change in querySnapshot!!.documentChanges) {
            if (change.type == DocumentChange.Type.ADDED) {
                Log.d(TAG, "New city: ${change.document.data}")
            }

            val source = if (querySnapshot.metadata.isFromCache) {
                "local cache"
            } else {
                "server"
            }
            Log.d(TAG, "Data fetched from $source")
        }
    }

Java

db.collection("cities").whereEqualTo("state", "CA")
        .addSnapshotListener(MetadataChanges.INCLUDE, new EventListener<QuerySnapshot>() {
            @Override
            public void onEvent(@Nullable QuerySnapshot querySnapshot,
                                @Nullable FirebaseFirestoreException e) {
                if (e != null) {
                    Log.w(TAG, "Listen error", e);
                    return;
                }

                for (DocumentChange change : querySnapshot.getDocumentChanges()) {
                    if (change.getType() == Type.ADDED) {
                        Log.d(TAG, "New city:" + change.getDocument().getData());
                    }

                    String source = querySnapshot.getMetadata().isFromCache() ?
                            "local cache" : "server";
                    Log.d(TAG, "Data fetched from " + source);
                }

            }
        });

Dart

db
    .collection("cities")
    .where("state", isEqualTo: "CA")
    .snapshots(includeMetadataChanges: true)
    .listen((querySnapshot) {
  for (var change in querySnapshot.docChanges) {
    if (change.type == DocumentChangeType.added) {
      final source =
          (querySnapshot.metadata.isFromCache) ? "local cache" : "server";

      print("Data fetched from $source}");
    }
  }
});

Obtenez des données hors ligne

Si vous obtenez un document alors que l'appareil est hors ligne, Cloud Firestore renvoie les données du cache.

Lors de l'interrogation d'une collection, un résultat vide est renvoyé s'il n'y a aucun document en cache. Lors de la récupération d'un document spécifique, une erreur est renvoyée à la place.

Interroger des données hors ligne

L'interrogation fonctionne avec la persistance hors ligne. Vous pouvez récupérer les résultats des requêtes soit par obtention directe, soit par écoute, comme décrit dans les sections précédentes. Vous pouvez également créer de nouvelles requêtes sur des données conservées localement lorsque l'appareil est hors ligne, mais les requêtes s'exécuteront initialement uniquement sur les documents mis en cache.

Configurer les index de requêtes hors ligne

Par défaut, le SDK Firestore analyse tous les documents d'une collection dans son cache local lors de l'exécution de requêtes hors ligne. Avec ce comportement par défaut, les performances des requêtes hors ligne peuvent souffrir lorsque les utilisateurs sont hors ligne pendant de longues périodes.

Avec le cache persistant activé, vous pouvez améliorer les performances des requêtes hors ligne en permettant au SDK de créer automatiquement des index de requêtes locales.

L'indexation automatique est désactivée par défaut. Votre application doit activer l'indexation automatique à chaque démarrage. Contrôlez si l'indexation automatique est activée, comme indiqué ci-dessous.

Rapide
if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
    
Objectif c
PersistentCacheIndexManager *indexManager = [FIRFirestore firestore].persistentCacheIndexManager;
if (indexManager) {
  // Indexing is disabled by default
  [indexManager enableIndexAutoCreation];
}
    

Kotlin+KTX

// return type: PersistentCacheManager?

Firebase.firestore.persistentCacheIndexManager?.apply {
      // Indexing is disabled by default
      enableIndexAutoCreation()
    } ?: println("indexManager is null")
    

Java

// return type: @Nullable PersistentCacheIndexManager
PersistentCacheIndexManager indexManager = FirebaseFirestore.getInstance().getPersistentCacheIndexManager();
if (indexManager != null) {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation();
}

// If not check indexManager != null, IDE shows warning: Method invocation 'enableIndexAutoCreation' may produce 'NullPointerException' 
FirebaseFirestore.getInstance().getPersistentCacheIndexManager().enableIndexAutoCreation();
    

Une fois l'indexation automatique activée, le SDK évalue quelles collections contiennent un grand nombre de documents en cache et optimise les performances des requêtes locales.

Le SDK fournit une méthode de suppression des index de requête.

Désactiver et activer l'accès au réseau

Vous pouvez utiliser la méthode ci-dessous pour désactiver l'accès au réseau pour votre client Cloud Firestore. Lorsque l'accès au réseau est désactivé, tous les écouteurs d'instantanés et demandes de documents récupèrent les résultats du cache. Les opérations d'écriture sont mises en file d'attente jusqu'à ce que l'accès au réseau soit réactivé.

Web modular API

import { disableNetwork } from "firebase/firestore"; 

await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...

Web namespaced API

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
Rapide
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
Objectif c
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];

Kotlin+KTX

db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}

Java

db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });

Dart

db.disableNetwork().then((_) {
  // Do offline things
});

Utilisez la méthode suivante pour réactiver l'accès au réseau :

Web modular API

import { enableNetwork } from "firebase/firestore"; 

await enableNetwork(db);
// Do online actions
// ...

Web namespaced API

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
Rapide
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
Objectif c
Remarque : ce produit n'est pas disponible sur les cibles watchOS et App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];

Kotlin+KTX

db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}

Java

db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });

Dart

db.enableNetwork().then((_) {
  // Back online
});