Accedi ai dati offline

Cloud Firestore supporta la persistenza dei dati offline. Questa funzionalità memorizza nella cache una copia dei dati Cloud Firestore che la tua app sta utilizzando attivamente, in modo che l'app possa accedere ai dati quando il dispositivo è offline. Puoi scrivere, leggere, ascoltare ed eseguire query sui dati memorizzati nella cache. Quando il dispositivo torna online, Cloud Firestore sincronizza tutte le modifiche locali apportate dalla tua app al backend Cloud Firestore.

Nota: la persistenza offline è supportata solo nelle app Android, Apple e Web.

Per utilizzare la persistenza offline, non è necessario apportare modifiche al codice utilizzato per accedere ai dati Cloud Firestore. Con la persistenza offline abilitata, la libreria client Cloud Firestore gestisce automaticamente l'accesso ai dati online e offline e sincronizza i dati locali quando il dispositivo è di nuovo online.

Configura la persistenza offline

Quando inizializzi Cloud Firestore, puoi abilitare o disabilitare la persistenza offline:

• Per le piattaforme Android e Apple, la persistenza offline è abilitata per impostazione predefinita. Per disabilitare la persistenza, impostare l'opzione PersistenceEnabled su false .
• Per il Web, la persistenza offline è disabilitata per impostazione predefinita. Per abilitare la persistenza, chiamare il metodo enablePersistence . La cache di Cloud Firestore non viene cancellata automaticamente tra una sessione e l'altra. Di conseguenza, se la tua app Web gestisce informazioni riservate, assicurati di chiedere all'utente se si trova su un dispositivo attendibile prima di abilitare la persistenza.

Importante: per il Web, la persistenza offline è supportata solo dai browser Web Chrome, Safari e Firefox.

Web modular API

Scopri di più sull'SDK modulare Web v9 shakeable e sull'aggiornamento dalla versione 8.

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

Scopri di più sull'SDK modulare Web v9 shakeable e sull'aggiornamento dalla versione 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
test.firestore.js

Veloce

Nota: questo prodotto non è disponibile sui target watchOS e 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
ViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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;
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

Configura la dimensione della cache

Quando la persistenza è abilitata, Cloud Firestore memorizza nella cache tutti i documenti ricevuti dal backend per l'accesso offline. Cloud Firestore imposta una soglia predefinita per la dimensione della cache. Dopo aver superato l'impostazione predefinita, Cloud Firestore tenta periodicamente di ripulire i documenti più vecchi e non utilizzati. Puoi configurare una soglia diversa per la dimensione della cache o disabilitare completamente il processo di pulizia:

Web modular API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

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

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

Web namespaced API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js

Veloce

Nota: questo prodotto non è disponibile sui target watchOS e 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
ViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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;
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

Ascolta i dati offline

Mentre il dispositivo è offline, se hai abilitato la persistenza offline, i tuoi ascoltatori riceveranno eventi di ascolto quando cambiano i dati memorizzati nella cache locale. Puoi ascoltare documenti, raccolte e query.

Per verificare se stai ricevendo dati dal server o dalla cache, utilizza la proprietà fromCache su SnapshotMetadata nell'evento snapshot. Se fromCache è true , i dati provengono dalla cache e potrebbero essere obsoleti o incompleti. Se fromCache è false , i dati sono completi e aggiornati con gli ultimi aggiornamenti sul server.

Per impostazione predefinita, non viene generato alcun evento se è stato modificato solo SnapshotMetadata . Se ti affidi ai valori fromCache , specifica l'opzione di ascolto includeMetadataChanges quando colleghi il gestore di ascolto.

Web modular API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

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 namespaced API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

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

Veloce

Nota: questo prodotto non è disponibile sui target watchOS e 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)")
  }
ViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e 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);
    }];
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

Ottieni dati offline

Se ricevi un documento mentre il dispositivo è offline, Cloud Firestore restituisce i dati dalla cache.

Quando si esegue una query su una raccolta, viene restituito un risultato vuoto se non sono presenti documenti memorizzati nella cache. Quando si recupera un documento specifico, viene invece restituito un errore.

Interroga i dati offline

L'esecuzione di query funziona con la persistenza offline. È possibile recuperare i risultati delle query con un get diretto o tramite ascolto, come descritto nelle sezioni precedenti. Puoi anche creare nuove query sui dati persistenti localmente mentre il dispositivo è offline, ma le query verranno inizialmente eseguite solo sui documenti memorizzati nella cache.

Configura indici di query offline

Per impostazione predefinita, l'SDK di Firestore esegue la scansione di tutti i documenti in una raccolta nella cache locale durante l'esecuzione di query offline. Con questo comportamento predefinito, le prestazioni delle query offline possono risentirne quando gli utenti restano offline per lunghi periodi di tempo.

Con la cache permanente abilitata, puoi migliorare le prestazioni delle query offline consentendo all'SDK di creare automaticamente indici di query locali.

L'indicizzazione automatica è disabilitata per impostazione predefinita. La tua app deve abilitare l'indicizzazione automatica a ogni avvio. Controlla se l'indicizzazione automatica è abilitata come mostrato di seguito.

Veloce

if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
    

Obiettivo-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();
    

Una volta abilitata l'indicizzazione automatica, l'SDK valuta quali raccolte dispongono di un numero elevato di documenti memorizzati nella cache e ottimizza le prestazioni delle query locali.

L'SDK fornisce un metodo per eliminare gli indici delle query.

Disabilitare e abilitare l'accesso alla rete

Puoi utilizzare il metodo seguente per disabilitare l'accesso alla rete per il tuo client Cloud Firestore. Mentre l'accesso alla rete è disabilitato, tutti i listener di snapshot e le richieste di documenti recuperano i risultati dalla cache. Le operazioni di scrittura vengono accodate finché l'accesso alla rete non viene riabilitato.

Web modular API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

import { disableNetwork } from "firebase/firestore"; 

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

Web namespaced API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js

Veloce

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

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

Utilizzare il seguente metodo per riattivare l'accesso alla rete:

Web modular API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

import { enableNetwork } from "firebase/firestore"; 

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

Web namespaced API

Scopri di più sull'API Web modulare modificabile ad albero e sull'aggiornamento dall'API con spazio dei nomi.

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js

Veloce

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift

Obiettivo-C

Nota: questo prodotto non è disponibile sui target watchOS e App Clip.

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