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