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">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#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#privacy">Privacy API samples</a>. 98 </p> 99 100
