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