| <h2 id="overview">Overview</h2> |
| |
| <p> |
| This API has been optimized |
| to meet the specific storage needs of extensions. |
| It provides the same storage capabilities as the |
| <a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage API</a> |
| with the following key differences: |
| </p> |
| |
| <ul> |
| <li>User data can be automatically synced with Chrome sync |
| (using <code>storage.sync</code>).</li> |
| <li>Your extension's content scripts can directly access user data |
| without the need for a background page.</li> |
| <li>A user's extension settings can be persisted |
| even when using |
| <a href="manifest/incognito.html">split incognito behavior</a>.</li> |
| <li>It's asynchronous with bulk read and write operations, and therefore |
| faster than the blocking and serial <code>localStorage API</code>. |
| <li>User data can be stored as objects |
| (the <code>localStorage API</code> stores data in strings).</li> |
| </ul> |
| |
| <h2 id="manifest">Manifest</h2> |
| <p>You must declare the "storage" permission in the <a |
| href="manifest.html">extension manifest</a> |
| to use the storage API. |
| For example:</p> |
| <pre>{ |
| "name": "My extension", |
| ... |
| <b>"permissions": [ |
| "storage" |
| ]</b>, |
| ... |
| }</pre> |
| |
| <h2 id="using-sync">Usage</h2> |
| |
| <p> |
| To store user data for your extension, |
| you can use either |
| <code>storage.sync</code> or |
| <code>storage.local</code>. |
| When using <code>storage.sync</code>, |
| the stored data will automatically be synced |
| to any Chrome browser that the user is logged into, |
| provided the user has sync enabled. |
| </p> |
| |
| <p> |
| When Chrome is offline, |
| Chrome stores the data locally. |
| The next time the browser is online, |
| Chrome syncs the data. |
| Even if a user disables syncing, |
| <code>storage.sync</code> will still work. |
| In this case, it will behave identically |
| to <code>storage.local</code>. |
| </p> |
| |
| <p class="warning"> |
| Confidential user information should not be stored! |
| The storage area isn't encrypted. |
| </p> |
| |
| <h2 id="limits">Storage and throttling limits</h2> |
| |
| <p><code>chrome.storage</code> is not a big truck. |
| It's a series of tubes. |
| And if you don't understand, |
| those tubes can be filled, |
| and if they are filled |
| when you put your message in, |
| it gets in line, |
| and it's going to be delayed |
| by anyone that puts into that tube |
| enormous amounts of material. |
| |
| <p>For details on the current limits |
| of the storage API, and what happens |
| when those limits are exceeded, please |
| see the quota information for |
| <a href="#sync-properties">sync</a> and |
| <a href="#local-properties">local</a>. |
| |
| <h2 id="examples">Examples</h2> |
| |
| <p> |
| The following example checks for |
| CSS code saved by a user on a form, |
| and if found, |
| stores it. |
| </p> |
| |
| <pre> |
| function saveChanges() { |
| // Get a value saved in a form. |
| var theValue = textarea.value; |
| // Check that there's some code there. |
| if (!theValue) { |
| message('Error: No value specified'); |
| return; |
| } |
| // Save it using the Chrome extension storage API. |
| chrome.storage.sync.set({'value': theValue}, function() { |
| // Notify that we saved. |
| message('Settings saved'); |
| }); |
| } |
| </pre> |
| |
| <p> |
| If you're interested in tracking changes made |
| to a data object, |
| you can add a listener |
| to its <code>onChanged</code> event. |
| Whenever anything changes in storage, |
| that event fires. |
| Here's sample code |
| to listen for saved changes: |
| </p> |
| |
| <pre> |
| chrome.storage.onChanged.addListener(function(changes, namespace) { |
| for (key in changes) { |
| var storageChange = changes[key]; |
| console.log('Storage key "%s" in namespace "%s" changed. ' + |
| 'Old value was "%s", new value is "%s".', |
| key, |
| namespace, |
| storageChange.oldValue, |
| storageChange.newValue); |
| } |
| }); |
| </pre> |