chrome/common/extensions/docs/templates/intros/storage.html

   1 <h2 id="overview">Overview</h2>
   2
   3 <p>
   4 This API has been optimized
   5 to meet the specific storage needs of extensions.
   6 It provides the same storage capabilities as the
   7 <a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage API</a>
   8 with the following key differences:
   9 </p>
  10
  11 <ul>
  12   <li>User data can be automatically synced with Chrome sync
  13   (using <code>storage.sync</code>).</li>
  14   <li>Your {{platform}}'s content scripts can directly access user data
  15   without the need for a background page.</li>
  16   <li>A user's extension settings can be persisted
  17   even when using
  18   <a href="manifest/incognito">split incognito behavior</a>.</li>
  19   <li>It's asynchronous with bulk read and write operations, and therefore
  20   faster than the blocking and serial <code>localStorage API</code>.
  21   <li>User data can be stored as objects
  22   (the <code>localStorage API</code> stores data in strings).</li>
  23   <li>Enterprise policies configured by the administrator for the extension
  24   can be read (using <code>storage.managed</code> with a
  25   <a href="manifest/storage">schema</a>).</li>
  26 </ul>
  27
  28 <h2 id="manifest">Manifest</h2>
  29 <p>You must declare the "storage" permission in the <a
  30   href="manifest">extension manifest</a>
  31   to use the storage API.
  32   For example:</p>
  33 <pre data-filename="manifest.json">
  34 {
  35   "name": "My extension",
  36   ...
  37   <b>"permissions": [
  38     "storage"
  39   ]</b>,
  40   ...
  41 }
  42 </pre>
  43
  44 <h2 id="using-sync">Usage</h2>
  45
  46 <p>
  47 To store user data for your {{platform}},
  48 you can use either
  49 <code>storage.sync</code> or
  50 <code>storage.local</code>.
  51 When using <code>storage.sync</code>,
  52 the stored data will automatically be synced
  53 to any Chrome browser that the user is logged into,
  54 provided the user has sync enabled.
  55 </p>
  56
  57 <p>
  58 When Chrome is offline,
  59 Chrome stores the data locally.
  60 The next time the browser is online,
  61 Chrome syncs the data.
  62 Even if a user disables syncing,
  63 <code>storage.sync</code> will still work.
  64 In this case, it will behave identically
  65 to <code>storage.local</code>.
  66 </p>
  67
  68 <p class="warning">
  69 Confidential user information should not be stored!
  70 The storage area isn't encrypted.
  71 </p>
  72
  73 <p>
  74 The <code>storage.managed</code> storage is read-only.
  75 </p>
  76
  77 <h2 id="limits">Storage and throttling limits</h2>
  78
  79 <p><code>chrome.storage</code> is not a big truck.
  80 It's a series of tubes.
  81 And if you don't understand,
  82 those tubes can be filled,
  83 and if they are filled
  84 when you put your message in,
  85 it gets in line,
  86 and it's going to be delayed
  87 by anyone that puts into that tube
  88 enormous amounts of material.
  89
  90 <p>For details on the current limits
  91 of the storage API, and what happens
  92 when those limits are exceeded, please
  93 see the quota information for
  94 $(ref:sync) and $(ref:local).
  95
  96 <h2 id="examples">Examples</h2>
  97
  98 <p>
  99 The following example checks for
 100 CSS code saved by a user on a form,
 101 and if found,
 102 stores it.
 103 </p>
 104
 105 <pre>
 106 function saveChanges() {
 107   // Get a value saved in a form.
 108   var theValue = textarea.value;
 109   // Check that there's some code there.
 110   if (!theValue) {
 111     message('Error: No value specified');
 112     return;
 113   }
 114   // Save it using the Chrome extension storage API.
 115   chrome.storage.sync.set({'value': theValue}, function() {
 116     // Notify that we saved.
 117     message('Settings saved');
 118   });
 119 }
 120 </pre>
 121
 122 <p>
 123 If you're interested in tracking changes made
 124 to a data object,
 125 you can add a listener
 126 to its <code>onChanged</code> event.
 127 Whenever anything changes in storage,
 128 that event fires.
 129 Here's sample code
 130 to listen for saved changes:
 131 </p>
 132
 133 <pre>
 134 chrome.storage.onChanged.addListener(function(changes, namespace) {
 135   for (key in changes) {
 136     var storageChange = changes[key];
 137     console.log('Storage key "%s" in namespace "%s" changed. ' +
 138                 'Old value was "%s", new value is "%s".',
 139                 key,
 140                 namespace,
 141                 storageChange.oldValue,
 142                 storageChange.newValue);
 143   }
 144 });
 145 </pre>