Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(127)

Side by Side Diff: chrome/common/extensions/docs/privacy.html

Issue 9244005: Move the `privacy` extension API out of experimental. (Closed) Base URL: http://git.chromium.org/git/chromium.git@trunk
Patch Set: License. Created 8 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
2 1) The <head> information in this page is significant, should be uniform 2 1) The <head> information in this page is significant, should be uniform
3 across api docs and should be edited only with knowledge of the 3 across api docs and should be edited only with knowledge of the
4 templating mechanism. 4 templating mechanism.
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
6 browser, it will be re-generated from the template, json schema and 6 browser, it will be re-generated from the template, json schema and
7 authored overview content. 7 authored overview content.
8 4) The <body>.innerHTML is also generated by an offline step so that this 8 4) The <body>.innerHTML is also generated by an offline step so that this
9 page may easily be indexed by search engines. 9 page may easily be indexed by search engines.
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print">
14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla te_compiled.js">
15 </script> 15 </script>
16 <script type="text/javascript" src="js/api_page_generator.js"></script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script>
17 <script type="text/javascript" src="js/bootstrap.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script>
18 <script type="text/javascript" src="js/sidebar.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script>
19 <meta name="description" content="Documentation for the chrome.experimental.pr ivacy module, which is part of the Google Chrome extension APIs."><title>chrome .experimental.privacy - Google Chrome Extensions - Google Code</title></head> 19 <meta name="description" content="Documentation for the chrome.privacy module, which is part of the Google Chrome extension APIs."><title>Privacy - Google Ch rome Extensions - Google Code</title></head>
20 <body> <div id="devModeWarning" class="displayModeWarning"> 20 <body> <div id="devModeWarning" class="displayModeWarning">
21 You are viewing extension docs in chrome via the 'file:' scheme: are you exp ecting to see local changes when you refresh? You'll need run chrome with --allo w-file-access-from-files. 21 You are viewing extension docs in chrome via the 'file:' scheme: are you exp ecting to see local changes when you refresh? You'll need run chrome with --allo w-file-access-from-files.
22 </div> 22 </div>
23 <div id="branchWarning" class="displayModeWarning"> 23 <div id="branchWarning" class="displayModeWarning">
24 <span>WARNING: This is the <span id="branchName">BETA</span> documentation. 24 <span>WARNING: This is the <span id="branchName">BETA</span> documentation.
25 It may not work with the stable release of Chrome.</span> 25 It may not work with the stable release of Chrome.</span>
26 <select id="branchChooser"> 26 <select id="branchChooser">
27 <option>Choose a different version... 27 <option>Choose a different version...
28 </option><option value="">Stable 28 </option><option value="">Stable
29 </option><option value="beta">Beta 29 </option><option value="beta">Beta
(...skipping 274 matching lines...) Expand 10 before | Expand all | Expand 10 after
304 </ul> 304 </ul>
305 </li> 305 </li>
306 </ul> 306 </ul>
307 </div> 307 </div>
308 <script> 308 <script>
309 initToggles(); 309 initToggles();
310 </script> 310 </script>
311 311
312 <div class="g-unit" id="gc-pagecontent"> 312 <div class="g-unit" id="gc-pagecontent">
313 <div id="pageTitle"> 313 <div id="pageTitle">
314 <h1 class="page_title">chrome.experimental.privacy</h1> 314 <h1 class="page_title">Privacy</h1>
315 </div> 315 </div>
316 <!-- TABLE OF CONTENTS --> 316 <!-- TABLE OF CONTENTS -->
317 <div id="toc"> 317 <div id="toc">
318 <h2>Contents</h2> 318 <h2>Contents</h2>
319 <ol> 319 <ol>
320 <li style="display: none; "> 320 <li>
321 <a>h2Name</a> 321 <a href="#manifest">Manifest</a>
322 <ol> 322 <ol>
323 <li> 323 <li style="display: none; ">
324 <a>h3Name</a>
325 </li>
326 </ol>
327 </li><li>
328 <a href="#usage">Usage</a>
329 <ol>
330 <li style="display: none; ">
331 <a>h3Name</a>
332 </li>
333 </ol>
334 </li><li>
335 <a href="#examples">Examples</a>
336 <ol>
337 <li style="display: none; ">
338 <a>h3Name</a>
339 </li>
340 </ol>
341 </li><li>
342 <a href="#manifest">Manifest</a>
343 <ol>
344 <li style="display: none; ">
345 <a>h3Name</a>
346 </li>
347 </ol>
348 </li><li>
349 <a href="#usage">Usage</a>
350 <ol>
351 <li style="display: none; ">
352 <a>h3Name</a>
353 </li>
354 </ol>
355 </li><li>
356 <a href="#examples">Examples</a>
357 <ol>
358 <li style="display: none; ">
324 <a>h3Name</a> 359 <a>h3Name</a>
325 </li> 360 </li>
326 </ol> 361 </ol>
327 </li> 362 </li>
328 <li> 363 <li>
329 <a href="#apiReference">API reference: chrome.experimental.priva cy</a> 364 <a href="#apiReference">API reference: chrome.privacy</a>
330 <ol> 365 <ol>
331 <li> 366 <li>
332 <a href="#properties">Properties</a> 367 <a href="#properties">Properties</a>
333 <ol> 368 <ol>
334 <li> 369 <li>
335 <a href="#property-network">network</a> 370 <a href="#property-network">network</a>
336 </li><li> 371 </li><li>
337 <a href="#property-services">services</a> 372 <a href="#property-services">services</a>
338 </li><li> 373 </li><li>
339 <a href="#property-websites">websites</a> 374 <a href="#property-websites">websites</a>
(...skipping 28 matching lines...) Expand all
368 </li> 403 </li>
369 </ol> 404 </ol>
370 </li> 405 </li>
371 </ol> 406 </ol>
372 </li> 407 </li>
373 </ol> 408 </ol>
374 </div> 409 </div>
375 <!-- /TABLE OF CONTENTS --> 410 <!-- /TABLE OF CONTENTS -->
376 411
377 <!-- Standard content lead-in for experimental API pages --> 412 <!-- Standard content lead-in for experimental API pages -->
378 <p id="classSummary"> 413 <p id="classSummary" style="display: none; ">
379 For information on how to use experimental APIs, see the <a href="expe rimental.html">chrome.experimental.* APIs</a> page. 414 For information on how to use experimental APIs, see the <a href="expe rimental.html">chrome.experimental.* APIs</a> page.
380 </p> 415 </p>
381 416
382 <!-- STATIC CONTENT PLACEHOLDER --> 417 <!-- STATIC CONTENT PLACEHOLDER -->
383 <div id="static"></div> 418 <div id="static"><div id="pageData-name" class="pageData">Privacy</div>
419
420 <!-- BEGIN AUTHORED CONTENT -->
421 <p id="classSummary">
422 Use the <code>chrome.privacy</code> module to control usage of the features in
423 Chrome that can affect a user's privacy. This module relies on the
424 <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a>
425 for getting and setting Chrome's configuration.
426 </p>
427
428 <p class="note">
429 The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privac y-whitepaper.pdf">Chrome Privacy Whitepaper</a>
430 gives background detail regarding the features which this API can control.
431 </p>
432
433 <h2 id="manifest">Manifest</h2>
434 <p>
435 You must declare the "privacy" permission in your extension's
436 <a href="manifest.html">manifest</a> to use the API. For example:
437 </p>
438
439 <pre>{
440 "name": "My extension",
441 ...
442 <b>"permissions": [
443 "privacy"
444 ]</b>,
445 ...
446 }</pre>
447
448 <h2 id="usage">Usage</h2>
449
450 <p>
451 Reading the current value of a Chrome setting is straightforward. You'll first
452 need to find the property you're interested in, then you'll call
453 <code>get()</code> on that object in order to retrieve it's current value and
454 your extension's level of control. For example, to determine if Chrome's
455 Autofill feature is enabled, you'd write:
456 </p>
457
458 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
459 if (details.value)
460 console.log('Autofill is on!');
461 else
462 console.log('Autofill is off!');
463 });</pre>
464
465 <p>
466 Changing the value of a setting is a little bit more complex, simply because
467 you first must verify that your extension can control the setting. The user
468 won't see any change to her settings if you extension toggles a setting that
469 is either locked to a specific value by enterprise policies
470 (<code>levelOfControl</code> will be set to "not_controllable"), or if another
471 extension is controlling the value (<code>levelOfControl</code> will be set to
472 "controlled_by_other_extensions"). The <code>set()</code> call will succeed,
473 but the setting will be immediately overridden. As this might be confusing, it
474 is advisable to warn the user when the settings they've chosen aren't
475 practically applied.
476 </p>
477
478 <p class="note">
479 Full details about extensions' ability to control <code>ChromeSetting</code>s
480 can be found under
481 <a href="types.html#ChromeSetting">
482 <code>chrome.types.ChromeSetting</code></a>.
483 </p>
484
485 <p>
486 This means that you ought to use the <code>get()</code> method to determine
487 your level of access, and then only call <code>set()</code> if your extension
488 can grab control over the setting (in fact if your extension can't control the
489 setting it's probably a good idea to visibly disable the functionality to
490 reduce user confusion):
491 </p>
492
493 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
494 if (details.levelOfControl === 'controllable_by_this_extension') {
495 chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
496 if (chrome.extension.lastError === undefined)
497 console.log("Hooray, it worked!");
498 else
499 console.log("Sadness!", chrome.extension.lastError);
500 }
501 }
502 });</pre>
503
504 <p>
505 If you're interested in changes to a setting's value, add a listener to its
506 <code>onChange</code> event. Among other uses, this will allow you to warn the
507 user if a more recently installed extension grabs control of a setting, or if
508 enterprise policy overrides your control. To listen for changes to Autofill's
509 status, for example, the following code would suffice:
510 </p>
511
512 <pre>chrome.privacy.services.autofillEnabled.onChange.addListener(
513 function (details) {
514 // The new value is stored in `details.value`, the new level of control
515 // in `details.levelOfControl`, and `details.incognitoSpecific` will be
516 // `true` if the value is specific to Incognito mode.
517 });</pre>
518
519 <h2 id="examples">Examples</h2>
520 <p>
521 For example code, see the
522 <a href="samples.html#privacy">Privacy API samples</a>.
523 </p>
524 <!-- END AUTHORED CONTENT --><div id="pageData-name" class="pageData">Privacy</d iv>
525
526 <!-- BEGIN AUTHORED CONTENT -->
527 <p id="classSummary">
528 Use the <code>chrome.privacy</code> module to control usage of the features in
529 Chrome that can affect a user's privacy. This module relies on the
530 <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a>
531 for getting and setting Chrome's configuration.
532 </p>
533
534 <p class="note">
535 The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privac y-whitepaper.pdf">Chrome Privacy Whitepaper</a>
536 gives background detail regarding the features which this API can control.
537 </p>
538
539 <h2 id="manifest">Manifest</h2>
540 <p>
541 You must declare the "privacy" permission in your extension's
542 <a href="manifest.html">manifest</a> to use the API. For example:
543 </p>
544
545 <pre>{
546 "name": "My extension",
547 ...
548 <b>"permissions": [
549 "privacy"
550 ]</b>,
551 ...
552 }</pre>
553
554 <h2 id="usage">Usage</h2>
555
556 <p>
557 Reading the current value of a Chrome setting is straightforward. You'll first
558 need to find the property you're interested in, then you'll call
559 <code>get()</code> on that object in order to retrieve it's current value and
560 your extension's level of control. For example, to determine if Chrome's
561 Autofill feature is enabled, you'd write:
562 </p>
563
564 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
565 if (details.value)
566 console.log('Autofill is on!');
567 else
568 console.log('Autofill is off!');
569 });</pre>
570
571 <p>
572 Changing the value of a setting is a little bit more complex, simply because
573 you first must verify that your extension can control the setting. The user
574 won't see any change to her settings if you extension toggles a setting that
575 is either locked to a specific value by enterprise policies
576 (<code>levelOfControl</code> will be set to "not_controllable"), or if another
577 extension is controlling the value (<code>levelOfControl</code> will be set to
578 "controlled_by_other_extensions"). The <code>set()</code> call will succeed,
579 but the setting will be immediately overridden. As this might be confusing, it
580 is advisable to warn the user when the settings they've chosen aren't
581 practically applied.
582 </p>
583
584 <p class="note">
585 Full details about extensions' ability to control <code>ChromeSetting</code>s
586 can be found under
587 <a href="types.html#ChromeSetting">
588 <code>chrome.types.ChromeSetting</code></a>.
589 </p>
590
591 <p>
592 This means that you ought to use the <code>get()</code> method to determine
593 your level of access, and then only call <code>set()</code> if your extension
594 can grab control over the setting (in fact if your extension can't control the
595 setting it's probably a good idea to visibly disable the functionality to
596 reduce user confusion):
597 </p>
598
599 <pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
600 if (details.levelOfControl === 'controllable_by_this_extension') {
601 chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
602 if (chrome.extension.lastError === undefined)
603 console.log("Hooray, it worked!");
604 else
605 console.log("Sadness!", chrome.extension.lastError);
606 }
607 }
608 });</pre>
609
610 <p>
611 If you're interested in changes to a setting's value, add a listener to its
612 <code>onChange</code> event. Among other uses, this will allow you to warn the
613 user if a more recently installed extension grabs control of a setting, or if
614 enterprise policy overrides your control. To listen for changes to Autofill's
615 status, for example, the following code would suffice:
616 </p>
617
618 <pre>chrome.privacy.services.autofillEnabled.onChange.addListener(
619 function (details) {
620 // The new value is stored in `details.value`, the new level of control
621 // in `details.levelOfControl`, and `details.incognitoSpecific` will be
622 // `true` if the value is specific to Incognito mode.
623 });</pre>
624
625 <h2 id="examples">Examples</h2>
626 <p>
627 For example code, see the
628 <a href="samples.html#privacy">Privacy API samples</a>.
629 </p>
630 <!-- END AUTHORED CONTENT -->
631 </div>
384 632
385 <!-- API PAGE --> 633 <!-- API PAGE -->
386 <div class="apiPage"> 634 <div class="apiPage">
387 <a name="apiReference"></a> 635 <a name="apiReference"></a>
388 <h2>API reference: chrome.experimental.privacy</h2> 636 <h2>API reference: chrome.privacy</h2>
389 637
390 <!-- PROPERTIES --> 638 <!-- PROPERTIES -->
391 <div class="apiGroup"> 639 <div class="apiGroup">
392 <a name="properties"></a> 640 <a name="properties"></a>
393 <h3 id="properties">Properties</h3> 641 <h3 id="properties">Properties</h3>
394 642
395 <div> 643 <div>
396 <a name="property-network"></a> 644 <a name="property-network"></a>
397 <h4>network</h4> 645 <h4>network</h4>
398 <div class="summary"> 646 <div class="summary">
399 <!-- Note: intentionally longer 80 columns --> 647 <!-- Note: intentionally longer 80 columns -->
400 <span>chrome.experimental.privacy.</span><span>network</span> 648 <span>chrome.privacy.</span><span>network</span>
401 </div> 649 </div>
402 <div> 650 <div>
403 <dt> 651 <dt>
404 <var>network</var> 652 <var>network</var>
405 <em> 653 <em>
406 654
407 <!-- TYPE --> 655 <!-- TYPE -->
408 <div style="display:inline"> 656 <div style="display:inline">
409 ( 657 (
410 <span class="optional" style="display: none; ">optional</spa n> 658 <span class="optional" style="display: none; ">optional</spa n>
(...skipping 118 matching lines...) Expand 10 before | Expand all | Expand 10 after
529 <dd style="display: none; "> 777 <dd style="display: none; ">
530 <div></div> 778 <div></div>
531 </dd> 779 </dd>
532 780
533 </div> 781 </div>
534 </div><div> 782 </div><div>
535 <a name="property-services"></a> 783 <a name="property-services"></a>
536 <h4>services</h4> 784 <h4>services</h4>
537 <div class="summary"> 785 <div class="summary">
538 <!-- Note: intentionally longer 80 columns --> 786 <!-- Note: intentionally longer 80 columns -->
539 <span>chrome.experimental.privacy.</span><span>services</span> 787 <span>chrome.privacy.</span><span>services</span>
540 </div> 788 </div>
541 <div> 789 <div>
542 <dt> 790 <dt>
543 <var>services</var> 791 <var>services</var>
544 <em> 792 <em>
545 793
546 <!-- TYPE --> 794 <!-- TYPE -->
547 <div style="display:inline"> 795 <div style="display:inline">
548 ( 796 (
549 <span class="optional" style="display: none; ">optional</spa n> 797 <span class="optional" style="display: none; ">optional</spa n>
(...skipping 232 matching lines...) Expand 10 before | Expand all | Expand 10 after
782 1030
783 <!-- FUNCTION PARAMETERS --> 1031 <!-- FUNCTION PARAMETERS -->
784 <dd style="display: none; "> 1032 <dd style="display: none; ">
785 <div></div> 1033 <div></div>
786 </dd> 1034 </dd>
787 1035
788 </div> 1036 </div>
789 </div><div> 1037 </div><div>
790 <div> 1038 <div>
791 <dt> 1039 <dt>
792 <var>metricsReportingEnabled</var>
793 <em>
794
795 <!-- TYPE -->
796 <div style="display:inline">
797 (
798 <span class="optional" style="display: none; ">optional</spa n>
799 <span class="enum" style="display: none; ">enumerated</span>
800 <span id="typeTemplate">
801 <span>
802 <a href="types.html#type-ChromeSetting">ChromeSetting</a >
803 </span>
804 <span style="display: none; ">
805 <span>
806 array of <span><span></span></span>
807 </span>
808 <span>paramType</span>
809 <span></span>
810 </span>
811 </span>
812 )
813 </div>
814
815 </em>
816 </dt>
817 <dd class="todo" style="display: none; ">
818 Undocumented.
819 </dd>
820 <dd>If enabled, Chrome automatically sends usage statistics and crash reports to Google. This preference's value is a boolean, defaulting to <code>fal se</code>.</dd>
821 <dd style="display: none; ">
822 This parameter was added in version
823 <b><span></span></b>.
824 You must omit this parameter in earlier versions,
825 and you may omit it in any version. If you require this
826 parameter, the manifest key
827 <a href="manifest.html#minimum_chrome_version">minimum_chrome_versio n</a>
828 can ensure that your extension won't be run in an earlier browser ve rsion.
829 </dd>
830
831 <!-- OBJECT PROPERTIES -->
832 <dd style="display: none; ">
833 <dl>
834 <div>
835 <div>
836 </div>
837 </div>
838 </dl>
839 </dd>
840
841 <!-- OBJECT METHODS -->
842 <dd style="display: none; ">
843 <div></div>
844 </dd>
845
846 <!-- OBJECT EVENT FIELDS -->
847 <dd style="display: none; ">
848 <div></div>
849 </dd>
850
851 <!-- FUNCTION PARAMETERS -->
852 <dd style="display: none; ">
853 <div></div>
854 </dd>
855
856 </div>
857 </div><div>
858 <div>
859 <dt>
860 <var>safeBrowsingEnabled</var> 1040 <var>safeBrowsingEnabled</var>
861 <em> 1041 <em>
862 1042
863 <!-- TYPE --> 1043 <!-- TYPE -->
864 <div style="display:inline"> 1044 <div style="display:inline">
865 ( 1045 (
866 <span class="optional" style="display: none; ">optional</spa n> 1046 <span class="optional" style="display: none; ">optional</spa n>
867 <span class="enum" style="display: none; ">enumerated</span> 1047 <span class="enum" style="display: none; ">enumerated</span>
868 <span id="typeTemplate"> 1048 <span id="typeTemplate">
869 <span> 1049 <span>
(...skipping 206 matching lines...) Expand 10 before | Expand all | Expand 10 after
1076 <dd style="display: none; "> 1256 <dd style="display: none; ">
1077 <div></div> 1257 <div></div>
1078 </dd> 1258 </dd>
1079 1259
1080 </div> 1260 </div>
1081 </div><div> 1261 </div><div>
1082 <a name="property-websites"></a> 1262 <a name="property-websites"></a>
1083 <h4>websites</h4> 1263 <h4>websites</h4>
1084 <div class="summary"> 1264 <div class="summary">
1085 <!-- Note: intentionally longer 80 columns --> 1265 <!-- Note: intentionally longer 80 columns -->
1086 <span>chrome.experimental.privacy.</span><span>websites</span> 1266 <span>chrome.privacy.</span><span>websites</span>
1087 </div> 1267 </div>
1088 <div> 1268 <div>
1089 <dt> 1269 <dt>
1090 <var>websites</var> 1270 <var>websites</var>
1091 <em> 1271 <em>
1092 1272
1093 <!-- TYPE --> 1273 <!-- TYPE -->
1094 <div style="display:inline"> 1274 <div style="display:inline">
1095 ( 1275 (
1096 <span class="optional" style="display: none; ">optional</spa n> 1276 <span class="optional" style="display: none; ">optional</spa n>
(...skipping 443 matching lines...) Expand 10 before | Expand all | Expand 10 after
1540 _uff=0; 1720 _uff=0;
1541 urchinTracker(); 1721 urchinTracker();
1542 } 1722 }
1543 catch(e) {/* urchinTracker not available. */} 1723 catch(e) {/* urchinTracker not available. */}
1544 </script> 1724 </script>
1545 <!-- end analytics --> 1725 <!-- end analytics -->
1546 </div> 1726 </div>
1547 </div> <!-- /gc-footer --> 1727 </div> <!-- /gc-footer -->
1548 </div> <!-- /gc-container --> 1728 </div> <!-- /gc-container -->
1549 </body></html> 1729 </body></html>
OLDNEW
« no previous file with comments | « chrome/common/extensions/docs/permission_warnings.html ('k') | chrome/common/extensions/docs/samples.html » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698