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