Mengakses data secara offline

Cloud Firestore mendukung persistensi data offline. Fitur ini meng-cache salinan data Cloud Firestore yang digunakan secara aktif oleh aplikasi Anda, sehingga aplikasi dapat mengakses data saat perangkat sedang offline. Anda dapat menulis, membaca, memproses, dan membuat kueri terhadap data yang di-cache. Saat perangkat kembali online, Cloud Firestore akan menyinkronkan semua perubahan lokal yang dilakukan oleh aplikasi Anda ke backend Cloud Firestore.

Untuk menggunakan persistensi offline, Anda tidak perlu membuat perubahan pada kode yang Anda gunakan untuk mengakses data Cloud Firestore. Dengan pengaktifan persistensi offline, library klien Cloud Firestore akan otomatis mengelola akses data online dan offline, serta menyinkronkan data lokal saat perangkat kembali online.

Mengonfigurasi persistensi offline

Saat menginisialisasi Cloud Firestore, Anda dapat mengaktifkan atau menonaktifkan persistensi offline:

  • Untuk platform Android dan Apple, persistensi offline diaktifkan secara default. Untuk menonaktifkan persistensi, setel opsi PersistenceEnabled ke false.
  • Untuk web, persistensi offline dinonaktifkan secara default. Untuk mengaktifkan persistensi, panggil metode enablePersistence. Cache Cloud Firestore tidak dihapus secara otomatis di antara sesi. Oleh karena itu, jika aplikasi web Anda menangani informasi sensitif, pastikan pengguna menggunakan perangkat dipercaya sebelum mengaktifkan persistensi.

API modular web

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

API dengan namespace web

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
Catatan: Produk ini tidak tersedia di target watchOS dan 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
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan 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;

Kotlin+KTX

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

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

Dart

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

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

Mengonfigurasi ukuran cache

Ketika persistensi diaktifkan, Cloud Firestore meng-cache setiap dokumen yang diterima dari backend untuk akses offline. Cloud Firestore menetapkan batas default untuk ukuran cache. Setelah melebihi batas default, Cloud Firestore secara berkala akan berupaya menghapus dokumen lama yang tidak digunakan. Anda dapat mengonfigurasi batas ukuran cache yang berbeda atau menonaktifkan proses penghapusan sepenuhnya:

API modular web

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

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

API dengan namespace web

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan 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
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan 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;
  

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

Memproses data offline

Saat perangkat sedang offline, jika Anda telah mengaktifkan persistensi offline, pemroses akan menerima peristiwa pemrosesan saat terjadi perubahan pada data yang di-cache secara lokal. Anda dapat memproses dokumen, koleksi, dan kueri.

Untuk memeriksa apakah Anda menerima data dari server atau cache, gunakan properti fromCache pada SnapshotMetadata di peristiwa snapshot Anda. Jika fromCache adalah true, artinya data berasal dari cache dan mungkin sudah tidak berlaku atau tidak lengkap. Jika fromCache adalah false, artinya data lengkap dan terkini dengan pembaruan terbaru di server.

Secara default, tidak ada peristiwa yang dipicu jika hanya SnapshotMetadata yang berubah. Jika Anda mengandalkan nilai fromCache, tentukan opsi pemroses includeMetadataChanges saat memasang pengendali pemrosesan Anda.

API modular web

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

API dengan namespace web

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
Catatan: Produk ini tidak tersedia di target watchOS dan 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)")
  }
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan 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);
    }];

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

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

            }
        });

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

Mendapatkan data offline

Jika Anda mendapatkan dokumen saat perangkat sedang offline, Cloud Firestore akan menampilkan data dari cache.

Saat membuat kueri terhadap koleksi, hasil kosong akan ditampilkan jika tidak ada dokumen yang di-cache. Saat mengambil dokumen tertentu, error akan ditampilkan.

Membuat kueri terhadap data offline

Pembuatan kueri dapat dilakukan dengan persistensi offline. Anda dapat mengambil hasil kueri dengan cara mendapatkannya secara langsung atau dengan memprosesnya, seperti yang dijelaskan di bagian sebelumnya. Anda juga dapat membuat kueri baru pada data yang disimpan secara lokal saat perangkat sedang offline, tetapi pada awalnya kueri tersebut hanya akan berjalan pada dokumen yang di-cache.

Mengonfigurasi indeks kueri offline

Secara default, Firestore SDK memindai semua dokumen dalam koleksi di cache lokalnya saat menjalankan kueri offline. Dengan perilaku default ini, performa kueri offline dapat terganggu saat pengguna offline untuk jangka waktu yang lama.

Dengan mengaktifkan cache persisten, Anda dapat meningkatkan performa kueri offline dengan mengizinkan SDK untuk membuat indeks kueri lokal secara otomatis.

Pengindeksan otomatis dinonaktifkan secara default. Aplikasi Anda harus mengaktifkan pengindeksan otomatis setiap kali dimulai. Kontrol apakah pengindeksan otomatis diaktifkan seperti yang ditunjukkan di bawah.

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

Setelah pengindeksan otomatis diaktifkan, SDK akan mengevaluasi koleksi mana yang memiliki banyak dokumen yang di-cache dan mengoptimalkan performa kueri lokal.

SDK menyediakan metode untuk menghapus indeks kueri.

Menonaktifkan dan mengaktifkan akses jaringan

Anda dapat menggunakan metode di bawah ini untuk menonaktifkan akses jaringan untuk klien Cloud Firestore. Saat akses jaringan dinonaktifkan, semua pemroses snapshot dan permintaan dokumen akan mengambil hasil dari cache. Operasi tulis dimasukkan ke dalam antrean sampai akses jaringan diaktifkan kembali.

API modular web

import { disableNetwork } from "firebase/firestore"; 

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

API dengan namespace web

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip.
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];

Kotlin+KTX

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

Java

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

Dart

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

Gunakan metode berikut untuk mengaktifkan kembali akses jaringan:

API modular web

import { enableNetwork } from "firebase/firestore"; 

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

API dengan namespace web

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip.
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];

Kotlin+KTX

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

Java

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

Dart

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