Offline auf Daten zugreifen

Cloud Firestore unterstützt die Offlinedatenpersistenz. Mit dieser Funktion wird eine Kopie der Cloud Firestore-Daten, die Ihre App aktiv verwendet, im Cache gespeichert, sodass Ihre App auf die Daten zugreifen kann, wenn das Gerät offline ist. Sie können die im Cache gespeicherten Daten schreiben, lesen, überwachen und abfragen. Wenn das Gerät wieder online ist, synchronisiert Cloud Firestore alle von Ihrer App vorgenommenen lokalen Änderungen mit dem Cloud Firestore-Back-End.

Wenn Sie die Offlinepersistenz verwenden möchten, müssen Sie keine Änderungen am Code vornehmen, mit dem Sie auf Cloud Firestore-Daten zugreifen. Wenn die Offlinepersistenz aktiviert ist, verwaltet die Cloud Firestore-Clientbibliothek automatisch den Online- und Offlinedatenzugriff und synchronisiert lokale Daten, wenn das Gerät wieder online ist.

Offlinepersistenz konfigurieren

Wenn Sie Cloud Firestore initialisieren, können Sie die Offlinepersistenz aktivieren oder deaktivieren:

  • Für Android- und Apple-Plattformen ist die Offlinepersistenz standardmäßig aktiviert. Zum Deaktivieren der Persistenz setzen Sie die Option PersistenceEnabled auf false.
  • Im Web ist die Offlinepersistenz standardmäßig deaktiviert. Zum Aktivieren der Persistenz rufen Sie die Methode enablePersistence auf. Der Cache von Cloud Firestore wird zwischen den Sitzungen nicht automatisch geleert. Wenn Ihre Web-App vertrauliche Informationen verarbeitet, sollten Sie daher den Nutzer fragen, ob er ein vertrauenswürdiges Gerät verwendet, bevor Sie die Persistenz aktivieren.

Web

// 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

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
test.firestore.js
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
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
ViewController.swift
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
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;
ViewController.m

Kotlin+KTX

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

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);
DocSnippets.java

Dart

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

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

Cache-Größe konfigurieren

Wenn die Persistenz aktiviert ist, speichert Cloud Firestore jedes vom Back-End empfangene Dokument für den Offlinezugriff im Cache. Cloud Firestore legt einen Standardgrenzwert für die Cache-Größe fest. Wenn der Standardwert überschritten wurde, versucht Cloud Firestore regelmäßig, ältere, nicht verwendete Dokumente zu bereinigen. Sie können einen anderen Schwellenwert für die Cache-Größe konfigurieren oder den Bereinigungsprozess vollständig deaktivieren:

Web

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

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

Web

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
// 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
ViewController.swift
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
// 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;
ViewController.m

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,
);
firestore.dart

Offlinedaten überwachen

Wenn Sie die Offlinepersistenz aktiviert haben, empfangen Ihre Listener während der Offlinenutzung entsprechende Ereignisse, wenn sich die lokal im Cache gespeicherten Daten ändern. Sie können Dokumente, Sammlungen und Abfragen überwachen.

Verwenden Sie das Attribut fromCache für die SnapshotMetadata in Ihrem Snapshot-Ereignis, um zu prüfen, ob Sie Daten vom Server oder vom Cache empfangen. Wenn fromCache den Wert true hat, kamen die Daten aus dem Cache und sind möglicherweise veraltet oder unvollständig. Wenn fromCache den Wert false hat, sind die Daten vollständig und spiegeln die neuesten Aktualisierungen auf dem Server wider.

Standardmäßig wird kein Ereignis ausgelöst, wenn nur die SnapshotMetadata geändert wurden. Wenn Sie sich auf die fromCache-Werte verlassen, geben Sie beim Anhängen Ihres Überwachungs-Handlers die Überwachungsoption includeMetadataChanges an.

Web

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);
    });
});
use_from_cache.js

Web

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);
      });
  });
test.firestore.js
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
// 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)")
  }
ViewController.swift
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
// 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);
    }];
ViewController.m

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")
        }
    }
DocSnippets.kt

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);
                }

            }
        });
DocSnippets.java

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}");
    }
  }
});
firestore.dart

Offlinedaten abrufen

Wenn Sie ein Dokument abrufen, während das Gerät offline ist, gibt Cloud Firestore Daten aus dem Cache zurück.

Beim Abfragen einer Sammlung wird ein leeres Ergebnis zurückgegeben, wenn keine Dokumente im Cache gespeichert sind. Beim Abrufen eines bestimmten Dokuments wird stattdessen ein Fehler zurückgegeben.

Offlinedaten abfragen

Die Abfrage funktioniert mit Offlinepersistenz. Sie können die Ergebnisse von Abfragen entweder mit einem direkten "get"-Aufruf oder durch Überwachung abrufen, wie in den vorherigen Abschnitten beschrieben. Sie können auch neue Abfragen für lokal beibehaltene Daten erstellen, während das Gerät offline ist. Die Abfragen werden jedoch anfangs nur für die im Cache gespeicherten Dokumente ausgeführt.

Indexe für Offlineabfragen konfigurieren

Standardmäßig scannt das Firestore SDK bei der Ausführung von Offlineabfragen alle Dokumente in einer Sammlung in seinem lokalen Cache. Bei diesem Standardverhalten kann die Leistung von Offlineabfragen beeinträchtigt werden, wenn Nutzer längere Zeit offline sind.

Wenn der persistente Cache aktiviert ist, können Sie die Leistung von Offlineabfragen verbessern, indem Sie dem SDK erlauben, automatisch lokale Abfrageindexe zu erstellen.

Die automatische Indexierung ist standardmäßig deaktiviert. Ihre App muss die automatische Indexierung bei jedem Start aktivieren. Legen Sie wie unten beschrieben fest, ob die automatische Indexierung aktiviert ist.

Swift
if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
Objective-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();

Sobald die automatische Indexierung aktiviert ist, prüft das SDK, welche Sammlungen eine große Anzahl von im Cache gespeicherten Dokumenten haben, und optimiert die Leistung lokaler Abfragen.

Das SDK bietet eine Methode zum Löschen von Abfrageindexen.

Netzwerkzugriff deaktivieren und aktivieren

Mit der folgenden Methode können Sie den Netzwerkzugriff für Ihren Cloud Firestore-Client deaktivieren. Während der Netzwerkzugriff deaktiviert ist, rufen alle Snapshot-Listener und Dokumentanfragen Ergebnisse aus dem Cache ab. Schreibvorgänge werden so lange in die Warteschlange gestellt, bis der Netzwerkzugriff wieder aktiviert wird.

Web

import { disableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin+KTX

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

Java

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

Dart

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

Verwenden Sie die folgende Methode, um den Netzwerkzugriff wieder zu aktivieren:

Web

import { enableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin+KTX

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

Java

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

Dart

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