B.6 Enable Offline Capabilities

Firebase apps work great offline and we have several features to make the experience even better. Enabling disk persistence allows your app to keep all of its state even after an app restart. We provide several tools for monitoring presence and connectivity state.

Disk Persistence

Firebase apps automatically handle temporary network interruptions for you. Cached data will still be available while offline and your writes will be resent when network connectivity is recovered. Enabling disk persistence allows our app to also keep all of its state even after an app restart. We can enable disk persistence with just one line of code.

DB.persistenceEnabled = true;

With disk persistence enabled, our synced data and writes will be persisted to disk across app restarts and our app should work seamlessly in offline situations.

Persistence Behavior By enabling persistence, any data that we sync while online will be persisted to disk and available offline, even when we restart the app. This means our app will work as it would online using the local data stored in the cache. Listener callbacks will continue to fire for local updates.

The Firebase Realtime Database client automatically keeps a queue of all write operations that are performed while our application is offline. When persistence is enabled, this queue will also be persisted to disk so all of our writes will be available when we restart the app. When the app regains connectivity, all of the operations will be sent to the server.

If our app uses Firebase Authentication, the client will persist the user's authentication token across restarts. If the auth token expires while our app is offline, the client will pause our write operations until we re-authenticate, else our writes might fail due to security rules.

Keeping Data Fresh The Firebase Realtime Database synchronizes and stores a local copy of the data for active listeners. In addition, you can keep specific locations in sync.

var myRef:DBReference = DB.getReference("scores");
myRef.keepSynced(true);

The client will automatically download the data at these locations and keep it in sync even if the reference has no active listeners. You can turn synchronization back off with the following line of code.

myRef.keepSynced(false);

By default, 10MB of previously synced data will be cached. This should be enough for most applications. If the cache outgrows its configured size, the Firebase Realtime Database will purge data that has been used least recently. Data that is kept in sync, will not be purged from the cache.

Querying Data Offline The Firebase Realtime Database stores data returned from a query for use when offline. For queries constructed while offline, the Firebase Realtime Database continues to work for previously loaded data. If the requested data hasn't loaded, the Firebase Realtime Database loads data from the local cache. When we come back online our data will load and reflect the query.

Handling Transactions Offline Any transactions that are performed while our app is offline, will be queued. Once the app regains network connectivity, the transactions will be sent to the server.

NOTE: Transactions are not persisted across app restarts. Even with persistence enabled, transactions are not persisted across app restarts. So you cannot rely on transactions done offline being committed to your Firebase Realtime Database. To provide the best user experience, your app should show that a transaction has not been saved into your { firebase_database} yet, or make sure your app remembers them manually and executes them again after an app restart.

NOTE: The Firebase Realtime Database has many features for dealing with offline scenarios and network connectivity. The rest of this guide applies to your app whether or not you have persistence enabled.

Managing Presence

In realtime applications it is often useful to detect when clients connect and disconnect. For example, we may want to mark a user as 'offline' when their client disconnects.

Firebase Database clients provide simple primitives that allow data to be written to the database when a client disconnects from the Firebase Database servers. These updates will occur whether the client disconnects cleanly or not, so we can rely on them to clean up data even if a connection is dropped or a client crashes. All write operations, including setting, updating, and removing, can be performed upon a disconnection.

Here is a simple example of writing data upon disconnection by using the whenDisconnect primitive:

DB.init();
var refDisconnect:DBReference = DB.getReference("disconnectmessage");
var whenDisconnected:DBWhenDisconnect = refDisconnect.whenDisconnect();
whenDisconnected.setValue("I disconnected!");

How whenDisconnect Works When an whenDisconnect() operation is established, it lives on the Firebase Realtime Database server. The server checks security to make sure the user can perform the write event requested, and informs the client if it is invalid. The server then monitors the connection. If at any point it times out, or is actively closed by the client, the server checks security a second time (to make sure the operation is still valid) and then invokes the event.

The client can listen to the following listeners on the write operation to ensure the whenDisconnect was correctly attached:

whenDisconnected.addEventListener(DBEvents.WHEN_DISCONNECT_SET_VALUE_SUCCESS, whenDisconnectedSetValueSuccess);
whenDisconnected.addEventListener(DBEvents.WHEN_DISCONNECT_SET_VALUE_FAILURE, whenDisconnectedSetValueFailure);

An whenDisconnect event can also be canceled by calling .cancel():

var whenDisconnected:DBWhenDisconnect = refDisconnect.whenDisconnect();
whenDisconnected.setValue("I disconnected!");

// some time later when we change our minds
whenDisconnected.cancel();