Attiva i dati offline

Attiva i dati offline

Firestore supporta la persistenza dei dati offline tramite l'integrazione con Firebase. Questa funzionalità facoltativa memorizza nella cache una copia dei dati di Firestore utilizzati attivamente dalla tua app, consentendo all'app di accedere ai dati mentre il dispositivo è offline. Puoi scrivere, leggere, ascoltare e interrogare i dati memorizzati nella cache su dispositivi mobili o in un browser web.

Quando il dispositivo torna online, Firestore sincronizza tutte le modifiche locali apportate dalla tua app al backend di Firestore. In caso di più modifiche allo stesso documento, vince l'ultima scrittura.

Nota:

• La persistenza offline è supportata solo nelle app Android, Apple e web.
• Le operazioni di pipeline non supportano la persistenza offline. Per utilizzare la persistenza offline con i database Enterprise Edition, utilizza le operazioni di base come descritto in questa pagina.

Per utilizzare la persistenza offline, non è necessario modificare il modo in cui il codice accede ai dati di Firestore. Quando attivi la persistenza offline, Firebase si coordina con Firestore per gestire automaticamente l'accesso ai dati online e offline e sincronizzare i dati locali quando il dispositivo torna online.

La persistenza offline richiede l'integrazione di Firebase per lo sviluppo di app web e mobile. Le librerie client lato server di Firestore per C#, Go, Java, Node.js, PHP, Python e Ruby non supportano la persistenza offline. Se l'utilizzo di Firebase non è approvato all'interno della tua organizzazione, utilizza queste librerie client lato server per evitare di dipendere da Firebase.

Configura la persistenza offline

Quando inizializzi un client Firestore, puoi attivare o disattivare la persistenza offline nei seguenti modi:

• Per le piattaforme Android e Apple, la persistenza offline è abilitata per impostazione predefinita. Per disattivare la persistenza, imposta l'opzione PersistenceEnabled su false.
• Per il web, la persistenza offline è disattivata per impostazione predefinita. Per attivare la persistenza, chiama il metodo enablePersistence. La cache di Firestore non viene svuotata automaticamente tra una sessione e l'altra. Di conseguenza, se la tua app web gestisce informazioni sensibili, assicurati di chiedere all'utente se si trova su un dispositivo attendibile prima di attivare la persistenza.

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

Web version 9

Scopri di più sull'SDK modulare Web v9 con tree shaking ed esegui l'upgrade 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()})
  });
  

Versione web 8

Scopri di più sull'SDK modulare Web v9 con tree shaking ed esegui l'upgrade 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

Swift

Nota: questo prodotto non è disponibile su 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

Objective-C

Nota: questo prodotto non è disponibile su 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
Android

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

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

Dart

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

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

Configura le dimensioni della cache

Quando la persistenza è abilitata, Firestore memorizza nella cache ogni documento ricevuto dal backend per l'accesso offline. Firestore imposta una soglia predefinita per le dimensioni della cache. Dopo aver superato il valore predefinito, Firestore tenta periodicamente di eliminare i documenti meno recenti e inutilizzati. Puoi configurare una soglia diversa per le dimensioni della cache o disattivare completamente il processo di pulizia:

Web version 9

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

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

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

Nota: questo prodotto non è disponibile su 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

Objective-C

Nota: questo prodotto non è disponibile su 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
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,
);
firestore.dart

Ascolta i dati offline

Mentre il dispositivo è offline, se hai attivato 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 ricevi i 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 il valore SnapshotMetadata. Se ti affidi ai 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);
    });
});
use_from_cache.js

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'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

Swift

Nota: questo prodotto non è disponibile su 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

Objective-C

Nota: questo prodotto non è disponibile su 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
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")
        }
    }
DocSnippets.kt

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

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

Recupera i dati offline

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

Quando esegui una query su una raccolta, viene restituito un risultato vuoto se non sono presenti documenti memorizzati nella cache. Quando recuperi un documento specifico, viene restituito un errore.

Esegui query sui dati offline

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

Configura gli indici delle query offline

Per impostazione predefinita, l'SDK Firestore analizza tutti i documenti di 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 sono 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 è disattivata per impostazione predefinita. L'app deve attivare l'indicizzazione automatica ogni volta che viene avviata. Controlla se l'indicizzazione automatica è abilitata come mostrato di seguito.

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

Una volta attivata l'indicizzazione automatica, l'SDK valuta quali raccolte hanno 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.

Disabilita e abilita l'accesso alla rete

Puoi utilizzare il metodo seguente per disattivare l'accesso alla rete per il tuo client Firestore. Mentre l'accesso alla rete è disattivato, tutti i listener di snapshot e le richieste di documenti recuperano i risultati dalla cache. Le operazioni di scrittura vengono messe in coda fino alla riattivazione dell'accesso alla rete.

Web version 9

import { disableNetwork } from "firebase/firestore"; 

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

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

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

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

Objective-C

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

[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin
Android

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

Java
Android

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

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

Web version 9

import { enableNetwork } from "firebase/firestore"; 

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

Versione web 8

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Swift

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

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

Objective-C

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

[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin
Android

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

Java
Android

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