Enable Offline Data
Cloud Firestore supports offline data persistence. This feature caches a copy of the Cloud Firestore data that your app is actively using, so your app can access the data when the device is offline. You can write, read, listen to, and query the cached data. When the device comes back online, Cloud Firestore synchronizes any local changes made by your app to the data stored remotely in Cloud Firestore.
Note: Offline persistence is supported only in Android, iOS, and web apps.To use offline persistence, you don't need to make any changes to the code that you use to access Cloud Firestore data. With offline persistence enabled, the Cloud Firestore client library automatically manages online and offline data access and synchronizes local data when the device is back online.
Configure offline persistence
When you initialize Cloud Firestore, you can enable or disable offline persistence:
- For Android and iOS, offline persistence is enabled by default. To disable persistence, set the
PersistenceEnabled
option tofalse
. - For the web, offline persistence is disabled by default. To enable persistence, call the
enablePersistence
method. Cloud Firestore's cache isn't automatically cleared between sessions. Consequently, if your web app handles sensitive information, make sure to ask the user if they're on a trusted device before enabling persistence.
settings . persistenceEnabled = YES ;
// Any additional options
// ...
// Enable offline data persistence
FIRFirestore * db = [ FIRFirestore firestore ];
db . settings = settings ;
Listen to offline data
While the device is offline, if you have enabled offline persistence, your listeners will receive listen events when the locally cached data changes. You can listen to documents, collections, and queries.
To check whether you're receiving data from the server or the cache, use the fromCache
property on the SnapshotMetadata
in your snapshot event. If fromCache
is true
, the data came from the cache and might be stale or incomplete. If fromCache
is false
, the data is complete and current with the latest updates on the server.
By default, no event is raised if only the SnapshotMetadata
changed. If you rely on the fromCache
values, specify the includeMetadataChanges
listen option when you attach your listen handler.
// the data is the same as the cached data.
FIRQueryListenOptions * options = [ FIRQueryListenOptions options ];
[ options includeQueryMetadataChanges : YES ];
[[[ db collectionWithPath :@ "cities" ] queryWhereField :@ "state" isEqualTo :@ "CA" ]
addSnapshotListenerWithOptions : options
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 );
}];
Get offline data
If you get a document while the device is offline, Cloud Firestore returns data from the cache. If the cache does not contain data for that document, or the document does not exist, the get call returns an error.
Query offline data
Querying works with offline persistence. You can retrieve the results of queries with either a direct get or by listening, as described in the preceding sections. You can also create new queries on locally persisted data while the device is offline, but the queries will initially run only against the cached documents.