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

   1 <p class="note">
   2   The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a>
   3   gives background detail regarding the features which this API can control.
   4 </p>
   5
   6 <h2 id="manifest">Manifest</h2>
   7 <p>
   8   You must declare the "privacy" permission in your extension's
   9   <a href="manifest.html">manifest</a> to use the API. For example:
  10 </p>
  11
  12 <pre data-filename="manifest.json">
  13 {
  14   "name": "My extension",
  15   ...
  16   <b>"permissions": [
  17     "privacy"
  18   ]</b>,
  19   ...
  20 }
  21 </pre>
  22
  23 <h2 id="usage">Usage</h2>
  24
  25 <p>
  26   Reading the current value of a Chrome setting is straightforward. You'll first
  27   need to find the property you're interested in, then you'll call
  28   <code>get()</code> on that object in order to retrieve its current value and
  29   your extension's level of control. For example, to determine if Chrome's
  30   Autofill feature is enabled, you'd write:
  31 </p>
  32
  33 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
  34   if (details.value)
  35     console.log('Autofill is on!');
  36   else
  37     console.log('Autofill is off!');
  38 });</pre>
  39
  40 <p>
  41   Changing the value of a setting is a little bit more complex, simply because
  42   you first must verify that your extension can control the setting. The user
  43   won't see any change to her settings if your extension toggles a setting that
  44   is either locked to a specific value by enterprise policies
  45   (<code>levelOfControl</code> will be set to "not_controllable"), or if another
  46   extension is controlling the value (<code>levelOfControl</code> will be set to
  47   "controlled_by_other_extensions"). The <code>set()</code> call will succeed,
  48   but the setting will be immediately overridden. As this might be confusing, it
  49   is advisable to warn the user when the settings they've chosen aren't
  50   practically applied.
  51 </p>
  52
  53 <p class="note">
  54   Full details about extensions' ability to control <code>ChromeSetting</code>s
  55   can be found under
  56   <a href="types.html#ChromeSetting">
  57     <code>chrome.types.ChromeSetting</code></a>.
  58 </p>
  59
  60 <p>
  61   This means that you ought to use the <code>get()</code> method to determine
  62   your level of access, and then only call <code>set()</code> if your extension
  63   can grab control over the setting (in fact if your extension can't control the
  64   setting it's probably a good idea to visually disable the functionality to
  65   reduce user confusion):
  66 </p>
  67
  68 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
  69   if (details.levelOfControl === 'controllable_by_this_extension') {
  70     chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
  71       if (chrome.runtime.lastError === undefined)
  72         console.log("Hooray, it worked!");
  73       else
  74         console.log("Sadness!", chrome.runtime.lastError);
  75     }
  76   }
  77 });</pre>
  78
  79 <p>
  80   If you're interested in changes to a setting's value, add a listener to its
  81   <code>onChange</code> event. Among other uses, this will allow you to warn the
  82   user if a more recently installed extension grabs control of a setting, or if
  83   enterprise policy overrides your control. To listen for changes to Autofill's
  84   status, for example, the following code would suffice:
  85 </p>
  86
  87 <pre>chrome.privacy.services.autofillEnabled.onChange.addListener(
  88     function (details) {
  89       // The new value is stored in `details.value`, the new level of control
  90       // in `details.levelOfControl`, and `details.incognitoSpecific` will be
  91       // `true` if the value is specific to Incognito mode.
  92     });</pre>
  93
  94 <h2 id="examples">Examples</h2>
  95 <p>
  96   For example code, see the
  97   <a href="samples.html#privacy">Privacy API samples</a>.
  98 </p>
  99