Jangan lewatkan sorotan dari Firebase di Google I/O 2023. Pelajari lebih lanjut

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

// 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 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
test.firestore.js
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
ViewController.swift
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;
ViewController.m

Kotlin+KTX

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

Java

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(true)
        .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

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
});
fs_setup_cache.js

Web version 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
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
ViewController.swift
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;
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

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 pemrosesan includeMetadataChanges saat memasang pengendali pemrosesan 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);
    });
});
use_from_cache.js

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);
      });
  });
test.firestore.js
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)")
}
ViewController.swift
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);
    }];
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

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.

Anda dapat meningkatkan performa kueri offline dengan mengonfigurasi indeks kueri lokal:

Swift

SDK platform Apple menyediakan metode setIndexConfiguration yang membaca konfigurasi terstruktur JSON yang sama dengan yang digunakan untuk mengonfigurasi indeks di server, dengan mengikuti format definisi indeks yang sama.

// You will normally read this from a file asset or cloud storage.
let indexConfigJson = """
  {
    indexes: [
        ...
    ],
    fieldOverrides: [
        ...
    ]
  }
"""

// Apply the configuration.
Firestore.firestore().setIndexConfiguration(indexConfigJson)
Objective-C

SDK platform Apple menyediakan metode setIndexConfiguration- yang membaca konfigurasi terstruktur JSON yang sama dengan yang digunakan untuk mengonfigurasi indeks di server, dengan mengikuti format definisi indeks yang sama.

// You will normally read this from a file asset or cloud storage.
NSString *indexConfigJson = @" {                   "
                             "   indexes: [        "
                             "     ...             "
                             "   ],                "
                             "   fieldOverrides: [ "
                             "     ...             "
                             "   ]                 "
                             " }                   ";

// Apply the configuration.
[[FIRFirestore firestore] setIndexConfigurationFromJSON:indexConfigJson
                                             completion:^(NSError * _Nullable error) {
    // ...
}];

Java

Android SDK menyediakan metode setIndexConfiguration yang membaca konfigurasi terstruktur JSON yang sama dengan yang digunakan untuk mengonfigurasi indeks di server, dengan mengikuti format definisi indeks yang sama.

// You will normally read this from a file asset or cloud storage.
String indexConfigJson = " {                   "
                       + "   indexes: [        "
                       + "     ...             "
                       + "   ],                "
                       + "   fieldOverrides: [ "
                       + "     ...             "
                       + "   ]                 "
                       + " }                   ";
// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson);

Kotlin+KTX

Android SDK menyediakan metode setIndexConfiguration yang membaca konfigurasi terstruktur JSON yang sama dengan yang digunakan untuk mengonfigurasi indeks di server, dengan mengikuti format definisi indeks yang sama.

// You will normally read this from a file asset or cloud storage.
val indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
"""

// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson)

Dart

Flutter SDK menyediakan metode setIndexConfigurationFromJSON yang membaca konfigurasi terstruktur JSON yang sama dengan yang digunakan untuk mengonfigurasi indeks di server, dengan mengikuti format definisi indeks yang sama.

// You will normally read this from a file asset or cloud storage.
var indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
""";

// Apply the configuration.
await FirebaseFirestore.instance.setIndexConfigurationFromJSON(json: indexConfigJson);

Atau, Anda dapat menggunakan metode setIndexConfiguration untuk mengonfigurasi indeks dengan API berbasis class.

var indexes = [
  Index(
    collectionGroup: "posts",
    queryScope: QueryScope.collection,
    fields: [
      IndexField(fieldPath: "author", arrayConfig: ArrayConfig.contains),
      IndexField(fieldPath: "timestamp", order: Order.descending)
    ],
  ),
];
await FirebaseFirestore.instance.setIndexConfiguration(indexes: indexes);

Konfigurasi indeks offline yang akan digunakan bergantung pada koleksi dan dokumen yang paling sering diakses aplikasi Anda saat offline dan performa offline yang Anda inginkan. Meski Anda dapat mengekspor konfigurasi indeks backend untuk digunakan pada klien, pola akses offline aplikasi Anda mungkin sangat jauh berbeda dari pola akses online, sehingga konfigurasi indeks online Anda mungkin tidak cocok untuk digunakan secara offline. Koleksi dan dokumen manakah yang Anda inginkan untuk diakses oleh aplikasi secara offline dengan performa tinggi? Setelah menganalisis perilaku aplikasi, ikuti prinsip definisi indeks dari panduan pengindeksan.

Agar konfigurasi indeks offline tersedia untuk dimuat di aplikasi klien:

  • kompilasikan dan distribusikan dengan aplikasi Anda
  • download konfigurasi dari CDN
  • ambil dari sistem penyimpanan seperti Cloud Storage for Firebase.

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
// ...
disable_network.js

Web version 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip. 
Firestore.firestore().disableNetwork { (error) in
    // Do offline things
    // ...
}
ViewController.swift
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan 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

Gunakan metode berikut untuk mengaktifkan kembali akses jaringan:

Web version 9

import { enableNetwork } from "firebase/firestore";

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

Web version 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Swift
Catatan: Produk ini tidak tersedia di target watchOS dan App Clip. 
Firestore.firestore().enableNetwork { (error) in
    // Do online things
    // ...
}
ViewController.swift
Objective-C
Catatan: Produk ini tidak tersedia di target watchOS dan 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