110 lines
7.2 KiB
Markdown
110 lines
7.2 KiB
Markdown
|
---
|
|||
|
|
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/).
|