Offlinedaten aktivieren

Firestore unterstützt die Offlinedatenpersistenz durch die Integration in Firebase. Mit dieser optionalen Funktion wird eine Kopie der Firestore-Daten, die Ihre App aktiv verwendet, im Cache gespeichert. So kann Ihre App auf die Daten zugreifen, während das Gerät offline ist. Sie können die im Cache gespeicherten Daten auf Mobilgeräten oder in einem Webbrowser schreiben, lesen, abhören und abfragen.

Wenn das Gerät wieder online ist, synchronisiert Firestore alle von Ihrer Anwendung vorgenommenen lokalen Änderungen mit dem Firestore-Backend. Bei mehreren Änderungen am selben Dokument gilt: Der letzte Schreibvorgang gewinnt.

Wenn Sie die Offlinespeicherung verwenden, müssen Sie die Art und Weise, wie Ihr Code auf Firestore-Daten zugreift, nicht ändern. Wenn Sie die Offline-Persistenz aktivieren, koordiniert Firebase mit Firestore, um den Online- und Offlinedatenzugriff automatisch zu verwalten und lokale Daten zu synchronisieren, wenn das Gerät wieder online ist.

Für die Offlinepersistenz ist die Firebase-Integration für die Entwicklung von Mobil- und Web-Apps erforderlich. Die serverseitigen Firestore-Clientbibliotheken für C#, Go, Java, Node.js, PHP, Python und Ruby unterstützen keine Offlinespeicherung. Wenn Firebase in Ihrer Organisation nicht genehmigt ist, können Sie diese serverseitigen Clientbibliotheken verwenden, um nicht von Firebase abhängig zu sein.

Offlinepersistenz konfigurieren

Wenn Sie einen Firestore-Client initialisieren, können Sie die Offline-Persistenz auf folgende Weise 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 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.

Webversion 9

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

Webversion 8

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
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
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;
Kotlin
Android
val settings = firestoreSettings {
    // Use memory cache
    setLocalCacheSettings(memoryCacheSettings {})
    // Use persistent disk cache (default)
    setLocalCacheSettings(persistentCacheSettings {})
}
db.firestoreSettings = settings
Java
Android
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));

Cache-Größe konfigurieren

Wenn die Persistenz aktiviert ist, speichert Firestore jedes vom Backend empfangene Dokument für den Offlinezugriff im Cache. Firestore legt einen Standardgrenzwert für die Cache-Größe fest. Wenn der Standardwert überschritten wurde, versucht 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:

Webversion 9

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

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

Webversion 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
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
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;
Kotlin
Android

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

// 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,
);

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.

Webversion 9

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

Webversion 8

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);
      });
  });
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)")
  }
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);
    }];
Kotlin
Android
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
Android
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}");
    }
  }
});

Offlinedaten abrufen

Wenn Sie ein Dokument erhalten, während das Gerät offline ist, gibt 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.

Offline-Abfrageindexe konfigurieren

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

Wenn der nichtflüchtige 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 bei jedem Start die automatische Indexierung aktivieren. Sie können die automatische Indexierung wie unten gezeigt aktivieren oder deaktivieren.

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
Android
// return type: PersistentCacheManager?

Firebase.firestore.persistentCacheIndexManager?.apply {
      // Indexing is disabled by default
      enableIndexAutoCreation()
    } ?: println("indexManager is null")
Java
Android
// 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, wertet das SDK aus, welche Sammlungen eine große Anzahl von im Cache gespeicherten Dokumenten enthalten, 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 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.

Webversion 9

import { disableNetwork } from "firebase/firestore"; 

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

Webversion 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
Kotlin
Android
db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}
Java
Android
db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });

Dart

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

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

Webversion 9

import { enableNetwork } from "firebase/firestore"; 

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

Webversion 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
Swift
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
Objective-C
Hinweis: Dieses Produkt nicht ist auf WatchOS- und App Clip-Zielen verfügbar. 
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
Kotlin
Android
db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}
Java
Android
db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });

Dart

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