Settings API

Overview

This page proposes adding methods/events to chrome.settings to let extensions store settings data (assumed to be small pieces of string-like data) that is synced across a user's browser instances. Initially, the module would start in the chrome.experimental.settings namespace.

Use cases

Ever since extensions/apps sync was implemented, extension settings sync has been an oft-requested and anticipated feature. Syncing an extension's settings greatly enhances the usefulness of extension sync.

Could this API be part of the web platform?

No.

Do you expect this API to be fairly stable?

Yes. This API is based on the HTML5 storage spec which is unlikely to change much.

What UI does this API expose?

No additional UI is exposed. However, we may need to add UI to chrome://extensions for turning off settings sync for particular extensions. On the other hand, extension developers could do this themselves.

How could this API be abused?

An ill-behaved extension could create lots of data to sync, bogging down both the client and the server. This may also cause the user to be throttled, possibly affecting sync for other data types (e.g., bookmarks, preferences).

How would you implement your desired features if this API didn't exist?

Currently, extensions sync their settings by stuffing data in bookmarks. This is obviously very hacky and causes problems for sync.

Fires when a setting has been changed, either locally or from another browser instance.

Parameters

e ( StorageEvent )

Details of the setting that was changed.

The Storage object passed to the getSettings callback behaves very similarly to the localStorage object; it is persisted across browser restarts and is per-profile. However, any changes made to it may eventually be synced to other browser instances with synced turned on. Also, the onSettingsChanged event may be fired when changes from other browser instances are synced to the local one.

No guarantees are made as to how long it takes for changes to propagate, or even if they're propagated at all. Sync may be turned off, clients may be throttled, and other reasons may prevent or delay propagation.

Each top-level key-value pair is guaranteed to be synced atomically. That is, while settings["a"] and settings["b"] may be synced independently, two clients writing separate values to the same key will cause the final state to be either one or the other. However, the settings Storage object at worst behaves like another localStorage.

The storage limits for the settings Storage object are more stringent than localStorage; tentatively, it is planned that each key/value pair can have a maximum of 16kb, and the total storage for an extension cannot exceed 100kb. It is expected that the most common use case for this are small pieces of string-like data, e.g. settings and preferences.

Extension developers must take care not to modify settings too often or else they risk being throttled (if they do on the order of hundreds or thousands of changes in a 24 hour period).

Sync will only kick in after a call to getSettings to propagate any changed settings and/or apply any new settings. This means that an extension developer has some control on how often sync fires.

Uninstalling an extension currently clears all settings data for it. (This may be surprising in some cases; we may need to revisit this in the future.)

This API will have its own manifest permission ("settings") but won't trigger a warning.

chrome.extension.settings.getSettings(function(settings) { // While this callback is being invoked, the extension has exclusive access to the settings. // At other times the extension does not have access. We do this to avoid raciness between // multiple processes manipulating the data concurrently. var foo = settings.foo; settings.foo = foo + 1; // using settings object here is OK

window.setTimeout(function() { // This is invalid! The extension no longer has access to |settings|. We need to make it // so that trying to read or write from the settings object after the callback is complete // throws an error. alert(settings.foo); }, 1000);

// Access to the extension's settings goes away at the end of this callback.});

Open questions

Is there a need for syncing other types of data, e.g. large pieces of data or structured data?

Do we need anything for the enterprise use case? It may be useful to be able to provide a default settings object and maybe even to mark some settings non-editable.