Home | History | Annotate | Download | only in intros 
      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 extensions 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.html">extension
     40   manifest</a> with the <code>optional_permissions</code> key, using the
     41   same format as the <a href="declare_permissions.html#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.html">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 <h3 id="request"> Step 3: Request optional permissions </h3>
     81 <p>
     82   Request the permissions from within a user gesture using
     83   <code>permissions.request()</code>:
     84 <pre>
     85 document.querySelector('#my-button').addEventListener('click', function(event) {
     86   // Permissions must be requested from inside a user gesture, like a button's
     87   // click handler.
     88   chrome.permissions.request({
     89     permissions: ['tabs'],
     90     origins: ['http://www.google.com/']
     91   }, function(granted) {
     92     // The callback argument will be true if the user granted the permissions.
     93     if (granted) {
     94       doSomething();
     95     } else {
     96       doSomethingElse();
     97     }
     98   });
     99 });
    100 </pre>
    101 </p>
    102 
    103 <p>
    104   Chrome prompts the user if adding the permissions results in different
    105   <a href="permission_warnings.html">warning messages</a> than the user has
    106   already seen and accepted. For example, the previous code might result in
    107   a prompt like this:
    108 </p>
    109 
    110 <p style="text-align: center">
    111   <img src="{{static}}/images/perms-optional.png"
    112        alt="example permission confirmation prompt"
    113        width="490" height="193">
    114 </p>
    115 
    116 <h3 id="contains"> Step 4: Check the extension's current permissions </h3>
    117 <p>
    118   To check whether your extension has a specific permission or set of
    119   permissions, use <code>permission.contains()</code>:
    120 </p>
    121 
    122 <pre>
    123 chrome.permissions.contains({
    124   permissions: ['tabs'],
    125   origins: ['http://www.google.com/']
    126 }, function(result) {
    127   if (result) {
    128     // The extension has the permissions.
    129   } else {
    130     // The extension doesn't have the permissions.
    131   }
    132 });
    133 </pre>
    134 
    135 <h3 id="remove"> Step 5: Remove the permissions </h3>
    136 <p>
    137   You should remove permissions when you no longer need them.
    138   After a permission has been removed, calling
    139   <code>permissions.request()</code> usually adds the permission back without
    140   prompting the user.
    141 </p>
    142 
    143 <pre>
    144 chrome.permissions.remove({
    145   permissions: ['tabs'],
    146   origins: ['http://www.google.com/']
    147 }, function(removed) {
    148   if (removed) {
    149     // The permissions have been removed.
    150   } else {
    151     // The permissions have not been removed (e.g., you tried to remove
    152     // required permissions).
    153   }
    154 });
    155 </pre>
    156