Acessar dados off-line

O Cloud Firestore oferece suporte à persistência de dados offline. Este recurso armazena em cache uma cópia dos dados do Cloud Firestore que seu aplicativo está usando ativamente, para que seu aplicativo possa acessar os dados quando o dispositivo estiver off-line. Você pode escrever, ler, ouvir e consultar os dados armazenados em cache. Quando o dispositivo fica on-line novamente, o Cloud Firestore sincroniza todas as alterações locais feitas pelo seu aplicativo com o back-end do Cloud Firestore.

Observação: a persistência offline é suportada apenas em aplicativos Android, Apple e web.

Para usar a persistência offline, não é necessário fazer alterações no código usado para acessar os dados do Cloud Firestore. Com a persistência offline habilitada, a biblioteca cliente do Cloud Firestore gerencia automaticamente o acesso aos dados online e offline e sincroniza os dados locais quando o dispositivo estiver online novamente.

Configurar persistência offline

Ao inicializar o Cloud Firestore, você pode ativar ou desativar a persistência offline:

• Para plataformas Android e Apple, a persistência offline está habilitada por padrão. Para desabilitar a persistência, defina a opção PersistenceEnabled como false .
• Para a web, a persistência offline está desabilitada por padrão. Para habilitar a persistência, chame o método enablePersistence . O cache do Cloud Firestore não é limpo automaticamente entre sessões. Conseqüentemente, se seu aplicativo da web lida com informações confidenciais, pergunte ao usuário se ele está em um dispositivo confiável antes de ativar a persistência.

Importante: Para a web, a persistência offline é suportada apenas pelos navegadores Chrome, Safari e Firefox.

Web modular API

Saiba mais sobre o SDK modular Web v9 que pode ser modificado em árvore e atualize a partir da versão 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

Saiba mais sobre o SDK modular Web v9 que pode ser modificado em árvore e atualize a partir da versão 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

Rápido

Observação: este produto não está disponível em destinos 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

Objetivo-C

Observação: este produto não está disponível em destinos 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

Configurar o tamanho do cache

Quando a persistência está habilitada, o Cloud Firestore armazena em cache todos os documentos recebidos do back-end para acesso offline. O Cloud Firestore define um limite padrão para o tamanho do cache. Após exceder o padrão, o Cloud Firestore tenta periodicamente limpar documentos mais antigos e não utilizados. Você pode configurar um limite de tamanho de cache diferente ou desativar completamente o processo de limpeza:

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

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

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

Rápido

Observação: este produto não está disponível em destinos 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

Objetivo-C

Observação: este produto não está disponível em destinos 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

Ouça dados off-line

Enquanto o dispositivo estiver offline, se você tiver habilitado a persistência offline, seus ouvintes receberão eventos de escuta quando os dados armazenados em cache localmente forem alterados. Você pode ouvir documentos, coleções e consultas.

Para verificar se você está recebendo dados do servidor ou do cache, use a propriedade fromCache no SnapshotMetadata no seu evento de snapshot. Se fromCache for true , os dados vieram do cache e podem estar obsoletos ou incompletos. Se fromCache for false , os dados estarão completos e atualizados com as atualizações mais recentes no servidor.

Por padrão, nenhum evento será gerado se apenas o SnapshotMetadata for alterado. Se você confiar nos valores fromCache , especifique a opção de escuta includeMetadataChanges ao anexar seu manipulador de escuta.

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

Rápido

Observação: este produto não está disponível em destinos 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

Objetivo-C

Observação: este produto não está disponível em destinos 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

Obtenha dados off-line

Se você receber um documento enquanto o dispositivo estiver off-line, o Cloud Firestore retornará dados do cache.

Ao consultar uma coleção, um resultado vazio será retornado se não houver documentos em cache. Ao buscar um documento específico, um erro é retornado.

Consultar dados off-line

A consulta funciona com persistência offline. Você pode recuperar os resultados das consultas com get direto ou escutando, conforme descrito nas seções anteriores. Você também pode criar novas consultas em dados persistidos localmente enquanto o dispositivo estiver off-line, mas as consultas serão executadas inicialmente apenas nos documentos armazenados em cache.

Configurar índices de consulta offline

Por padrão, o SDK do Firestore verifica todos os documentos de uma coleção no cache local ao executar consultas off-line. Com esse comportamento padrão, o desempenho da consulta offline pode ser prejudicado quando os usuários ficam offline por longos períodos de tempo.

Com o cache persistente ativado, você pode melhorar o desempenho de consultas off-line, permitindo que o SDK crie índices de consulta locais automaticamente.

A indexação automática está desabilitada por padrão. Seu aplicativo deve ativar a indexação automática sempre que for iniciado. Controle se a indexação automática está habilitada conforme mostrado abaixo.

Rápido

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

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

Depois que a indexação automática estiver habilitada, o SDK avalia quais coleções possuem um grande número de documentos em cache e otimiza o desempenho de consultas locais.

O SDK fornece um método para excluir índices de consulta.

Desabilitar e habilitar o acesso à rede

Você pode usar o método abaixo para desativar o acesso à rede para seu cliente Cloud Firestore. Enquanto o acesso à rede estiver desabilitado, todos os listeners de snapshots e solicitações de documentos recuperam resultados do cache. As operações de gravação ficam na fila até que o acesso à rede seja reativado.

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { disableNetwork } from "firebase/firestore"; 

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

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

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

Objetivo-C

Observação: este produto não está disponível em destinos 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

Use o seguinte método para reativar o acesso à rede:

Web modular API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

import { enableNetwork } from "firebase/firestore"; 

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

Web namespaced API

Saiba mais sobre a API da Web modular que pode ser abalada em árvore e faça upgrade da API com namespace.

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

Rápido

Observação: este produto não está disponível em destinos watchOS e App Clip.

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

Objetivo-C

Observação: este produto não está disponível em destinos 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