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.

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
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip.
let settings = FirestoreSettings()
settings.isPersistenceEnabled = true

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

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:

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
});
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
settings.cacheSizeBytes = FirestoreCacheSizeUnlimited
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;
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,
);

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 mengandalkan nilai fromCache, tentukan opsi deteksi includeMetadataChanges saat memasang pengendali deteksi Anda.

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

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

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 terhadap dokumen yang di-cache.

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.

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

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

Gunakan metode berikut untuk mengaktifkan kembali akses jaringan:

Web version 9

import { enableNetwork } from "firebase/firestore";

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

Web version 8

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
  // ...
}];

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