chrome/common/extensions/docs/templates/intros/permissions.html

   1 <h2 id="howto"> Implementing optional permissions </h2>
   2
   3 <h3 id="types">
   4 Step 1: Decide which permissions are required and which are optional
   5 </h3>
   6
   7 <p>
   8 An extension can declare both required and optional permissions. In general, you should:
   9 <ul>
  10   <li>Use required permissions when they are needed for your extension’s basic functionality.</li>
  11   <li>Use optional permissions when they are needed for optional features in your extension.</li>
  12 </ul>
  13 </p>
  14
  15 <p>
  16 Advantages of <em>required</em> permissions:
  17 <ul>
  18   <li><strong>Fewer prompts:</strong>
  19       An extension can prompt the user once to accept all permissions.</li>
  20   <li><strong>Simpler development:</strong>
  21       Required permissions are guaranteed to be present.</li>
  22 </ul>
  23 </p>
  24
  25 <p>
  26 Advantages of <em>optional</em> permissions:
  27 <ul>
  28   <li><strong>Better security:</strong>
  29       Extensions run with fewer permissions since users only enable permissions that are needed.</li>
  30   <li><strong>Better information for users:</strong>
  31       An extension can explain why it needs a particular permission when the user enables the relevant feature.</li>
  32   <li><strong>Easier upgrades:</strong>
  33       When you upgrade your extension, Chrome will not disable it for your users if the upgrade adds optional rather than required permissions.</li>
  34 </ul>
  35 </p>
  36
  37 <h3 id="manifest"> Step 2: Declare optional permissions in the manifest </h3>
  38 <p>
  39   Declare optional permissions in your <a href="manifest">extension
  40   manifest</a> with the <code>optional_permissions</code> key, using the
  41   same format as the <a href="declare_permissions#manifest">permissions</a>
  42   field:
  43 </p>
  44
  45 <pre data-filename="manifest.json">
  46 {
  47   "name": "My extension",
  48   ...
  49   <b>"optional_permissions": [ "tabs", "http://www.google.com/" ],</b>
  50   ...
  51 }
  52 </pre>
  53
  54 <p>
  55 You can specify any of the following as optional
  56 <a href="declare_permissions">permissions</a>:
  57 <ul>
  58   <li><i>host permissions</i></li>
  59   <li>background</li>
  60   <li>bookmarks</li>
  61   <li>clipboardRead</li>
  62   <li>clipboardWrite</li>
  63   <li>contentSettings</li>
  64   <li>contextMenus</li>
  65   <li>cookies</li>
  66   <li>debugger</li>
  67   <li>history</li>
  68   <li>idle</li>
  69   <li>management</li>
  70   <li>notifications</li>
  71   <li>pageCapture</li>
  72   <li>tabs</li>
  73   <li>topSites</li>
  74   <li>webNavigation</li>
  75   <li>webRequest</li>
  76   <li>webRequestBlocking</li>
  77 </ul>
  78 </p>
  79
  80 <p>If you want to request hosts that you only discover at runtime, include
  81 <code>"http://*/"</code> and/or <code>"https://*/"</code> as an
  82 <code>optional_permission</code>.  This lets you specify any origin in
  83 $(ref:Permissions.origins) as long as it has a matching scheme.
  84 </p>
  85
  86 <h3 id="request"> Step 3: Request optional permissions </h3>
  87 <p>
  88   Request the permissions from within a user gesture using
  89   <code>permissions.request()</code>:
  90 <pre>
  91 document.querySelector('#my-button').addEventListener('click', function(event) {
  92   // Permissions must be requested from inside a user gesture, like a button's
  93   // click handler.
  94   chrome.permissions.request({
  95     permissions: ['tabs'],
  96     origins: ['http://www.google.com/']
  97   }, function(granted) {
  98     // The callback argument will be true if the user granted the permissions.
  99     if (granted) {
 100       doSomething();
 101     } else {
 102       doSomethingElse();
 103     }
 104   });
 105 });
 106 </pre>
 107 </p>
 108
 109 <p>
 110   Chrome prompts the user if adding the permissions results in different
 111   <a href="permission_warnings">warning messages</a> than the user has
 112   already seen and accepted. For example, the previous code might result in
 113   a prompt like this:
 114 </p>
 115
 116 <p style="text-align: center">
 117   <img src="{{static}}/images/perms-optional.png"
 118        alt="example permission confirmation prompt"
 119        width="490" height="193">
 120 </p>
 121
 122 <h3 id="contains"> Step 4: Check the extension's current permissions </h3>
 123 <p>
 124   To check whether your extension has a specific permission or set of
 125   permissions, use <code>permission.contains()</code>:
 126 </p>
 127
 128 <pre>
 129 chrome.permissions.contains({
 130   permissions: ['tabs'],
 131   origins: ['http://www.google.com/']
 132 }, function(result) {
 133   if (result) {
 134     // The extension has the permissions.
 135   } else {
 136     // The extension doesn't have the permissions.
 137   }
 138 });
 139 </pre>
 140
 141 <h3 id="remove"> Step 5: Remove the permissions </h3>
 142 <p>
 143   You should remove permissions when you no longer need them.
 144   After a permission has been removed, calling
 145   <code>permissions.request()</code> usually adds the permission back without
 146   prompting the user.
 147 </p>
 148
 149 <pre>
 150 chrome.permissions.remove({
 151   permissions: ['tabs'],
 152   origins: ['http://www.google.com/']
 153 }, function(removed) {
 154   if (removed) {
 155     // The permissions have been removed.
 156   } else {
 157     // The permissions have not been removed (e.g., you tried to remove
 158     // required permissions).
 159   }
 160 });
 161 </pre>