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">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>
    162