Source code
Revision control
Copy as Markdown
Other Tools
---
layout: post
title: "💾 Saving and restoring browser session state"
date: 2019-02-18 14:35:00 +0200
author: sebastian
---
Losing open tabs in a browser can be a painful experience for the user. By itself [SessionManager](https://mozac.org/api/mozilla.components.browser.session/-session-manager/) keeps its state only in memory. This means that something as simple as switching to a different app can cause Android to [kill the browser app's process and reclaim its resources](https://developer.android.com/guide/components/activities/process-lifecycle). The result of that: The next time the user switches back to the browser app they start with a fresh browser without any tabs open.
[Mozilla's Android Components](https://mozac.org/) come with two implementations of session storage and helpers to write your own easily.
## SessionStorage
The [SessionStorage](https://mozac.org/api/mozilla.components.browser.session.storage/-session-storage/) class that comes with the [browser-session](https://github.com/mozilla-mobile/android-components/tree/main/components/browser/session) component saves the state as a file on disk (using [AtomicFile](https://developer.android.com/reference/android/util/AtomicFile) under the hood). It can be used for a browser that wants to have a single state that gets saved and restored (like Fennec or Chrome).
```kotlin
val sessionStorage SessionStorage(applicationContext, engine)
val sessionManager = sessionManager(engine).apply {
sessionStorage.restore()?.let { snapshot -> restore(snapshot) }
}
```
ℹ️ Since restoring the last state requires a disk read, it is recommended to perform it off the main thread. This requires the app to gracefully handle the situation where the app starts without any sessions at first. [SessionManager](https://mozac.org/api/mozilla.components.browser.session/-session-manager/) will invoke [onSessionsRestored()](https://mozac.org/api/mozilla.components.browser.session/-session-manager/-observer/on-sessions-restored.html) on a registered [SessionManager.Observer](https://mozac.org/api/mozilla.components.browser.session/-session-manager/-observer/) after restoring has completed.
## SessionBundleStorage
Other than [SessionStorage](https://mozac.org/api/mozilla.components.browser.session.storage/-session-storage/) the [SessionBundleStorage](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/) implementation can save and restore from multiple states. State is saved as a Bundle in a database.
The storage is set up with a bundle lifetime. [SessionBundleStorage](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/) will only restore the last bundle if its lifetime has not expired. If there's no active bundle then a new empty bundle will be created to save the state.
```kotlin
val engine: Engine = ...
val sessionStorage = SessionBundleStorage(
applicationContext,
bundleLifetime = Pair(1, TimeUnit.HOURS)
val sessionManager = sessionManager(engine).apply {
// We launch a coroutine on the main thread. Once a snapshot has been restored
// we want to continue with it on the main thread.
GlobalScope.launch(Dispatchers.Main) {
// We restore on the IO dispatcher to not block the main thread:
val snapshot = async(Dispatchers.IO) {
val bundle = sessionStorage.restore()
// If we got a bundle then restore the snapshot from it
bundle.restoreSnapshot(engine)
}
// If we got a snapshot then restore it now:
snapshot.await()?.let { sessionManager.restore(it) }
}
}
```
The storage comes with an [API](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/#functions) that allows apps to build UIs to list, restore, save and remove bundles.
## AutoSave
Knowing when to save state, by calling [SessionStorage.save()](https://mozac.org/api/mozilla.components.browser.session.storage/-session-storage/save.html) or [SessionBundleStorage.save()](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/save.html), can be complicated. Restoring an outdated state can be an as bad a user experience as restoring no state at all.
The [AutoSave](https://mozac.org/api/mozilla.components.browser.session.storage/-auto-save/) class is a helper for configuring automatic saving of the browser state - and you can use it with [SessionStorage](https://mozac.org/api/mozilla.components.browser.session.storage/-session-storage/) as well as [SessionBundleStorage](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/).
```kotlin
sessionStorage.autoSave(sessionManager)
// Automatically save the state every 30 seconds:
.periodicallyInForeground(interval = 30, unit = TimeUnit.SECONDS)
// Save the state when the app goes to the background:
.whenGoingToBackground()
// Save the state whenever sessions change (e.g. a new tab got added or a website
// has completed loading).
.whenSessionsChange()
```
## Implementing your own SessionStorage
If neither [SessionStorage](https://mozac.org/api/mozilla.components.browser.session.storage/-session-storage/) nor [SessionBundleStorage](https://mozac.org/api/mozilla.components.feature.session.bundling/-session-bundle-storage/) satisfy the requirements of your app (e.g. you want to save the state in your favorite database or in a cloud-enabled storage) then it is possible to implement a custom storage.
The [AutoSave.Storage](https://mozac.org/api/mozilla.components.browser.session.storage/-auto-save/-storage/) interface from the [browser-session](https://github.com/mozilla-mobile/android-components/tree/main/components/browser/session) component defines the methods that are expected from a session storage. Technically it is not required to implement the interface if your app code is the only one interacting with the session store; but implementing the interface makes your implementation compatible with other components code. Specifically you can use [AutoSave](https://mozac.org/api/mozilla.components.browser.session.storage/-auto-save/) with any class implementing SessionStorage without any additional code.
The [SnapshotSerializer](https://mozac.org/api/mozilla.components.browser.session.storage/-snapshot-serializer/) class is helpful when translating snapshots from and to JSON.
```kotlin
class MyCustomStorage(
private val engine: Engine
) : AutoSave.Storage {
private val serializer = SnapshotSerializer()
override fun save(snapshot: SessionManager.Snapshot): Boolean {
val json = serializer.toJSON(snapshot)
// TODO: Save JSON custom storage.
// Signal that save operation was successful:
return true
}
fun restore(): SessionManager.Snapshot {
// TODO: Get JSON from custom storage.
val json = ...
return serializer.fromJSON(engine, json)
}
}
```
ℹ️ For simplicity the implementation above does not handle [JSONException](ad https://developer.android.com/reference/org/json/JSONException.html) which can be thrown by [SnapshotSerializer](https://mozac.org/api/mozilla.components.browser.session.storage/-snapshot-serializer/).