Accedi ai dati offline

Cloud Firestore supporta la persistenza dei dati offline. Questa funzione memorizza nella cache una copia dei dati di Cloud Firestore che la tua app sta utilizzando attivamente, in modo che la tua app possa accedere ai dati quando il dispositivo è offline. È possibile scrivere, leggere, ascoltare e interrogare i dati memorizzati nella cache. Quando il dispositivo torna online, Cloud Firestore sincronizza tutte le modifiche locali apportate dalla tua app al back-end di Cloud Firestore.

Per utilizzare la persistenza offline, non è necessario apportare modifiche al codice che utilizzi per accedere ai dati di Cloud Firestore. Con la persistenza offline abilitata, la libreria client di 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, chiama il metodo enablePersistence . La cache di Cloud Firestore non viene cancellata automaticamente tra le sessioni. 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.

Web version 9

import { enableIndexedDbPersistence } from "firebase/firestore"; 

enableIndexedDbPersistence(db)
  .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

Web version 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
Veloce
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
let settings = FirestoreSettings()
settings.isPersistenceEnabled = true

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];
settings.persistenceEnabled = YES;

// Any additional options
// ...

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

Java

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(true)
        .build();
db.setFirestoreSettings(settings);

Kotlin+KTX

val settings = firestoreSettings {
    isPersistenceEnabled = true
}
db.firestoreSettings = settings

Dart

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

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

Configura la dimensione della cache

Quando la persistenza è abilitata, Cloud Firestore memorizza nella cache tutti i documenti ricevuti dal back-end 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 meno recenti e inutilizzati. Puoi configurare una diversa soglia di dimensione della cache o disabilitare completamente il processo di pulizia:

Web version 9

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

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

Web version 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
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
settings.cacheSizeBytes = FirestoreCacheSizeUnlimited
Firestore.firestore().settings = settings
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;
settings.cacheSizeBytes = kFIRFirestoreCacheSizeUnlimited;
[FIRFirestore firestore].settings = 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);

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

Dart

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

Ascolta i dati offline

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

Per verificare se stai ricevendo dati dal server o dalla cache, usa la proprietà fromCache in 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 vengono modificati solo gli SnapshotMetadata . Se fai affidamento sui valori fromCache , specifica l'opzione di ascolto includeMetadataChanges quando colleghi il gestore di ascolto.

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

Web version 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);
      });
  });
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)")
}
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);
    }];

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

            }
        });

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

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

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'interrogazione 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 in locale mentre il dispositivo è offline, ma inizialmente le query verranno eseguite solo sui documenti memorizzati nella cache.

Disabilita e abilita 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 istantanee e le richieste di documenti recuperano i risultati dalla cache. Le operazioni di scrittura vengono messe in coda fino a quando l'accesso alla rete non viene riattivato.

Web version 9

import { disableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
Veloce
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
Firestore.firestore().disableNetwork { (error) in
    // Do offline things
    // ...
}
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];

Java

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

Kotlin+KTX

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

Dart

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

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

Web version 9

import { enableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
Veloce
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
Firestore.firestore().enableNetwork { (error) in
    // Do online things
    // ...
}
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];

Java

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

Kotlin+KTX

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

Dart

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