diff options
Diffstat (limited to 'chrome/common/extensions/docs/static/privacy.html')
| -rw-r--r-- | chrome/common/extensions/docs/static/privacy.html | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/chrome/common/extensions/docs/static/privacy.html b/chrome/common/extensions/docs/static/privacy.html new file mode 100644 index 0000000..bb8f852 --- /dev/null +++ b/chrome/common/extensions/docs/static/privacy.html @@ -0,0 +1,213 @@ +<div id="pageData-name" class="pageData">Privacy</div> + +<!-- BEGIN AUTHORED CONTENT --> +<p id="classSummary"> + Use the <code>chrome.privacy</code> module to control usage of the features in + Chrome that can affect a user's privacy. This module relies on the + <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a> + for getting and setting Chrome's configuration. +</p> + +<p class="note"> + The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a> + gives background detail regarding the features which this API can control. +</p> + +<h2 id="manifest">Manifest</h2> +<p> + You must declare the "privacy" permission in your extension's + <a href="manifest.html">manifest</a> to use the API. For example: +</p> + +<pre>{ + "name": "My extension", + ... + <b>"permissions": [ + "privacy" + ]</b>, + ... +}</pre> + +<h2 id="usage">Usage</h2> + +<p> + Reading the current value of a Chrome setting is straightforward. You'll first + need to find the property you're interested in, then you'll call + <code>get()</code> on that object in order to retrieve it's current value and + your extension's level of control. For example, to determine if Chrome's + Autofill feature is enabled, you'd write: +</p> + +<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) { + if (details.value) + console.log('Autofill is on!'); + else + console.log('Autofill is off!'); +});</pre> + +<p> + Changing the value of a setting is a little bit more complex, simply because + you first must verify that your extension can control the setting. The user + won't see any change to her settings if you extension toggles a setting that + is either locked to a specific value by enterprise policies + (<code>levelOfControl</code> will be set to "not_controllable"), or if another + extension is controlling the value (<code>levelOfControl</code> will be set to + "controlled_by_other_extensions"). The <code>set()</code> call will succeed, + but the setting will be immediately overridden. As this might be confusing, it + is advisable to warn the user when the settings they've chosen aren't + practically applied. +</p> + +<p class="note"> + Full details about extensions' ability to control <code>ChromeSetting</code>s + can be found under + <a href="types.html#ChromeSetting"> + <code>chrome.types.ChromeSetting</code></a>. +</p> + +<p> + This means that you ought to use the <code>get()</code> method to determine + your level of access, and then only call <code>set()</code> if your extension + can grab control over the setting (in fact if your extension can't control the + setting it's probably a good idea to visibly disable the functionality to + reduce user confusion): +</p> + +<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) { + if (details.levelOfControl === 'controllable_by_this_extension') { + chrome.privacy.services.autofillEnabled.set({ value: true }, function() { + if (chrome.extension.lastError === undefined) + console.log("Hooray, it worked!"); + else + console.log("Sadness!", chrome.extension.lastError); + } + } +});</pre> + +<p> + If you're interested in changes to a setting's value, add a listener to its + <code>onChange</code> event. Among other uses, this will allow you to warn the + user if a more recently installed extension grabs control of a setting, or if + enterprise policy overrides your control. To listen for changes to Autofill's + status, for example, the following code would suffice: +</p> + +<pre>chrome.privacy.services.autofillEnabled.onChange.addListener( + function (details) { + // The new value is stored in `details.value`, the new level of control + // in `details.levelOfControl`, and `details.incognitoSpecific` will be + // `true` if the value is specific to Incognito mode. + });</pre> + +<h2 id="examples">Examples</h2> +<p> + For example code, see the + <a href="samples.html#privacy">Privacy API samples</a>. +</p> +<!-- END AUTHORED CONTENT --><div id="pageData-name" class="pageData">Privacy</div> + +<!-- BEGIN AUTHORED CONTENT --> +<p id="classSummary"> + Use the <code>chrome.privacy</code> module to control usage of the features in + Chrome that can affect a user's privacy. This module relies on the + <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a> + for getting and setting Chrome's configuration. +</p> + +<p class="note"> + The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a> + gives background detail regarding the features which this API can control. +</p> + +<h2 id="manifest">Manifest</h2> +<p> + You must declare the "privacy" permission in your extension's + <a href="manifest.html">manifest</a> to use the API. For example: +</p> + +<pre>{ + "name": "My extension", + ... + <b>"permissions": [ + "privacy" + ]</b>, + ... +}</pre> + +<h2 id="usage">Usage</h2> + +<p> + Reading the current value of a Chrome setting is straightforward. You'll first + need to find the property you're interested in, then you'll call + <code>get()</code> on that object in order to retrieve it's current value and + your extension's level of control. For example, to determine if Chrome's + Autofill feature is enabled, you'd write: +</p> + +<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) { + if (details.value) + console.log('Autofill is on!'); + else + console.log('Autofill is off!'); +});</pre> + +<p> + Changing the value of a setting is a little bit more complex, simply because + you first must verify that your extension can control the setting. The user + won't see any change to her settings if you extension toggles a setting that + is either locked to a specific value by enterprise policies + (<code>levelOfControl</code> will be set to "not_controllable"), or if another + extension is controlling the value (<code>levelOfControl</code> will be set to + "controlled_by_other_extensions"). The <code>set()</code> call will succeed, + but the setting will be immediately overridden. As this might be confusing, it + is advisable to warn the user when the settings they've chosen aren't + practically applied. +</p> + +<p class="note"> + Full details about extensions' ability to control <code>ChromeSetting</code>s + can be found under + <a href="types.html#ChromeSetting"> + <code>chrome.types.ChromeSetting</code></a>. +</p> + +<p> + This means that you ought to use the <code>get()</code> method to determine + your level of access, and then only call <code>set()</code> if your extension + can grab control over the setting (in fact if your extension can't control the + setting it's probably a good idea to visibly disable the functionality to + reduce user confusion): +</p> + +<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) { + if (details.levelOfControl === 'controllable_by_this_extension') { + chrome.privacy.services.autofillEnabled.set({ value: true }, function() { + if (chrome.extension.lastError === undefined) + console.log("Hooray, it worked!"); + else + console.log("Sadness!", chrome.extension.lastError); + } + } +});</pre> + +<p> + If you're interested in changes to a setting's value, add a listener to its + <code>onChange</code> event. Among other uses, this will allow you to warn the + user if a more recently installed extension grabs control of a setting, or if + enterprise policy overrides your control. To listen for changes to Autofill's + status, for example, the following code would suffice: +</p> + +<pre>chrome.privacy.services.autofillEnabled.onChange.addListener( + function (details) { + // The new value is stored in `details.value`, the new level of control + // in `details.levelOfControl`, and `details.incognitoSpecific` will be + // `true` if the value is specific to Incognito mode. + });</pre> + +<h2 id="examples">Examples</h2> +<p> + For example code, see the + <a href="samples.html#privacy">Privacy API samples</a>. +</p> +<!-- END AUTHORED CONTENT --> |