breadcrumbs: API Proposals (New APIs Start Here) > chromium_link: Chromium chromium_os_link: Chromium OS home_link: Home page_name: settings title: Settings API title_hdr: |
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.
Are you willing and able to develop and maintain this API?
The sync team can develop and maintain this API.
Draft API spec
It might be helpful to refer to docs for the HTML5 storage spec: see this overview and the spec itself.
API Reference: chrome.experimental.settings (later chrome.extension.settings)
Methods
getSettings
chrome.experimental.settings.getSettings(function callback)
Parameters
callback ( function )
Callback function
The callback parameter should specify a function that looks like this:
function(Storage settings) {...}
settings ( Storage )
The settings Storage object. It is guaranteed that nothing else will access this (including sync) for the lifetime of the callback.
Events
onSettingsChanged
chrome.experimental.settings.onSettingChanged.addListener(function(StorageEvent e) {...});
Fires when a setting has been changed, either locally or from another browser instance.
Parameters
e ( StorageEvent )
Details of the setting that was changed.
Example usage:
// Imagine an extension that retrieves data from a particular URL.
chrome.experimental.settings.getSettings(function(settings) {
// Do initial frobnigation, setting a default value if necessary.
var dataUrl = settings[“dataUrl”];
if (!dataUrl) {
// This will be propagated to other browser instances after this
// callback.
dataUrl = settings[“dataUrl”] = “http://www.foo.com/mydata”;
}
doInitialFrobnigate(dataUrl);
});
// Do an update every time the dataUrl setting is changed (either
// locally or remotely).
chrome.experimental.settings.onSettingChanged.addListener(function(e) {
if (e.key == “dataUrl”) {
console.info("Changing data URL from " + e.oldValue + " to " + e.newValue);
doUpdateFrobnigate(e.newValue);
}
});
Example code demonstrating when it's okay to access the settings object:
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