src/chrome/common/extensions/docs/templates/intros/browsingData.html

   1 <h2 id="manifest">Manifest</h2>
   2
   3 <p>
   4   You must declare the "browsingData" permission in the
   5   <a href="manifest.html">extension manifest</a> to use this API.
   6 </p>
   7
   8 <pre data-filename="manifest.json">
   9 {
  10   "name": "My extension",
  11   ...
  12   <b>"permissions": [
  13     "browsingData",
  14   ]</b>,
  15   ...
  16 }
  17 </pre>
  18
  19 <h2 id="usage">Usage</h2>
  20
  21 <p>
  22   The simplest use-case for this API is a a time-based mechanism for clearing a
  23   user's browsing data. Your code should provide a timestamp which indicates the
  24   historical date after which the user's browsing data should be removed. This
  25   timestamp is formatted as the number of milliseconds since the Unix epoch
  26   (which can be retrieved from a JavaScript <code>Date</code> object via the
  27   <code>getTime</code> method).
  28 </p>
  29
  30 <p>
  31   For example, to clear all of a user's browsing data from the last week, you
  32   might write code as follows:
  33 </p>
  34
  35 <pre>var callback = function () {
  36   // Do something clever here once data has been removed.
  37 };
  38
  39 var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
  40 var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
  41 chrome.browsingData.remove({
  42   "since": oneWeekAgo
  43 }, {
  44   "appcache": true,
  45   "cache": true,
  46   "cookies": true,
  47   "downloads": true,
  48   "fileSystems": true,
  49   "formData": true,
  50   "history": true,
  51   "indexedDB": true,
  52   "localStorage": true,
  53   "pluginData": true,
  54   "passwords": true,
  55   "webSQL": true
  56 }, callback);</pre>
  57
  58 <p>
  59   The <code>chrome.browsingData.remove</code> method allows you to remove
  60   various types of browsing data with a single call, and will be much faster
  61   than calling multiple more specific methods. If, however, you only want to
  62   clear one specific type of browsing data (cookies, for example), the more
  63   granular methods offer a readable alternative to a call filled with JSON.
  64 </p>
  65
  66 <pre>var callback = function () {
  67   // Do something clever here once data has been removed.
  68 };
  69
  70 var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
  71 var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
  72 chrome.browsingData.removeCookies({
  73   "since": oneWeekAgo
  74 }, callback);</pre>
  75
  76 <p class="caution">
  77   <strong>Important</strong>: Removing browsing data involves a good deal of
  78   heavy lifting in the background, and can take <em>tens of seconds</em> to
  79   complete, depending on a user's profile. You should use the callback mechanism
  80   to keep your users up to date on the removal's status.
  81 </p>
  82
  83 <h2 id="origin_types">Origin Types</h2>
  84
  85 <p>
  86   Adding an <code>originTypes</code> property to the API's options object allows
  87   you to specify which types of origins ought to be effected. Currently, origins
  88   are divided into three categories:
  89 </p>
  90 <ul>
  91   <li>
  92     <code>unprotectedWeb</code> covers the general case of websites that users
  93     visit without taking any special action. If you don't specify an
  94     <code>originTypes</code>, the API defaults to removing data from unprotected
  95     web origins.
  96   </li>
  97   <li>
  98     <code>protectedWeb</code> covers those web origins that have been installed
  99     as hosted applications. Installing <a href="https://chrome.google.com/webstore/detail/aknpkdffaafgjchaibgeefbgmgeghloj">
 100     Angry Birds</a>, for example, protects the origin
 101     <code>http://chrome.angrybirds.com</code>, and removes it from the
 102     <code>unprotectedWeb</code> category. Please do be careful when triggering
 103     deletion of data for these origins: make sure your users know what they're
 104     getting, as this will irrevocably remove their game data. No one wants to
 105     knock tiny pig houses over more often than necessary.
 106   </li>
 107   <li>
 108     <code>extension</code> covers origins under the
 109     <code>chrome-extensions:</code> scheme. Removing extension data is, again,
 110     something you should be very careful about.
 111   </li>
 112 </ul>
 113 <p>
 114   We could adjust the previous example to remove only data from protected
 115   websites as follows:
 116 </p>
 117 <pre>var callback = function () {
 118   // Do something clever here once data has been removed.
 119 };
 120
 121 var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
 122 var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
 123 chrome.browsingData.remove({
 124   "since": oneWeekAgo,
 125   <b>"originTypes": {
 126     "protectedWeb": true
 127   }</b>
 128 }, {
 129   "appcache": true,
 130   "cache": true,
 131   "cookies": true,
 132   "downloads": true,
 133   "fileSystems": true,
 134   "formData": true,
 135   "history": true,
 136   "indexedDB": true,
 137   "localStorage": true,
 138   "serverBoundCertificates": true,
 139   "pluginData": true,
 140   "passwords": true,
 141   "webSQL": true
 142 }, callback);</pre>
 143
 144 <p class="caution">
 145   <strong>Seriously</strong>: Be careful with <code>protectedWeb</code> and
 146   <code>extension</code>. These are destructive operations that your users
 147   will write angry email about if they're not well-informed about what to
 148   expect when your extension removes data on their behalf.
 149 </p>
 150
 151 <h2 id="samples">Examples</h2>
 152 <p>
 153   Samples for the <code>browsingData</code> API are available
 154   <a href="samples.html#browsingData">on the samples page</a>.
 155 </p>