| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1 class="page_title">Permission Warnings</h1> |
| 2 <div id="pageData-showTOC" class="pageData">true</div> |
| 3 <!-- |
| 4 NOTE: When this doc is updated, the online help should also be updated: |
| 5 http://www.google.com/support/chrome_webstore/bin/answer.py?hl=en&answer=186213 |
| 6 We should periodically look at |
| 7 http://src.chromium.org/viewvc/chrome/trunk/src/chrome/app/generated_resources.g
rd?view=markup |
| 8 to make sure that we're covering all messages. Search for |
| 9 IDS_EXTENSION_PROMPT_WARNING |
| 10 (e.g. IDS_EXTENSION_PROMPT_WARNING_BROWSING_HISTORY). |
| 11 --> |
| 12 <p> |
| 13 To use most chrome.* APIs and extension capabilities, |
| 14 your extension must declare its intent in the |
| 15 <a href="manifest.html">manifest</a>, |
| 16 often in the "permissions" field. |
| 17 Some of these declarations |
| 18 result in a warning when |
| 19 a user installs your extension. |
| 20 </p> |
| 21 <p> |
| 22 When you autoupdate your extension, |
| 23 the user might see another warning |
| 24 if the extension requests new permissions. |
| 25 These new permissions might be new APIs that your extension uses, |
| 26 or they might be new websites |
| 27 that your extension needs access to. |
| 28 </p> |
| 29 <h2 id="examples"> Examples of permission warnings </h2> |
| 30 <p> |
| 31 Here's a typical dialog |
| 32 that a user might see when installing an extension: |
| 33 </p> |
| 34 <img src="{{static}}/images/perms-hw1.png" |
| 35 width="410" height="193" |
| 36 alt="Permission warning: 'It can: Access your data on api.flickr.com'" |
| 37 /> |
| 38 <p> |
| 39 The warning about access to data on api.flickr.com |
| 40 is caused by the following lines |
| 41 in the extension's manifest: |
| 42 </p> |
| 43 <pre> |
| 44 "permissions": [ |
| 45 <b>"http://api.flickr.com/"</b> |
| 46 ], |
| 47 </pre> |
| 48 <p class="note"> |
| 49 <b>Note:</b> |
| 50 You don't see permission warnings when |
| 51 you load an unpacked extension. |
| 52 You get permission warnings only when you install an extension |
| 53 from a <code>.crx</code> file. |
| 54 </p> |
| 55 <p> |
| 56 If you add a permission to the extension when you autoupdate it, |
| 57 the user might see a new permission warning. |
| 58 For example, |
| 59 assume you add a new site and the "tabs" permission |
| 60 to the previous example: |
| 61 </p> |
| 62 <pre> |
| 63 "permissions": [ |
| 64 "http://api.flickr.com/", |
| 65 <b>"http://*.flickr.com/", |
| 66 "tabs"</b> |
| 67 ], |
| 68 </pre> |
| 69 <p> |
| 70 When the extension autoupdates, |
| 71 the increased permissions |
| 72 cause the extension to be disabled |
| 73 until the user re-enables it. |
| 74 Here's the warning the user sees: |
| 75 </p> |
| 76 <img src="{{static}}/images/perms-hw2-disabled.png" |
| 77 width="814" height="30" |
| 78 alt="Warning text: 'The newest version of the extension Hello World requires m
ore permissions, so it has been disabled. [Re-enable].'" |
| 79 /> |
| 80 <p> |
| 81 Clicking the Re-enable button |
| 82 brings up the following warning: |
| 83 </p> |
| 84 <img src="{{static}}/images/perms-hw2.png" |
| 85 width="412" height="220" |
| 86 alt="Permission warning: 'It can: Access your data on api.flickr.com and flick
r.com; Read and modify your browsing history'" |
| 87 /> |
| 88 <h2 id="warnings"> Warnings and their triggers </h2> |
| 89 <p> |
| 90 It can be surprising when adding a permission such as "tabs" |
| 91 results in the seemingly unrelated warning |
| 92 that the extension can access your browsing activity. |
| 93 The reason for the warning is that |
| 94 although the <code>chrome.tabs</code> API |
| 95 might be used only to open new tabs, |
| 96 it can also be used to see the URL that's associated |
| 97 with every newly opened tab |
| 98 (using their <a href="tabs.html#type-tabs.Tab">Tab</a> objects). |
| 99 </p> |
| 100 <p class="note"> |
| 101 <b>Note:</b> |
| 102 As of Google Chrome 7, |
| 103 you no longer need to specify the "tabs" permission |
| 104 just to call <code>chrome.tabs.create()</code> |
| 105 or <code>chrome.tabs.update()</code>. |
| 106 </p> |
| 107 <p> |
| 108 The following table lists the warning messages |
| 109 that users can see, |
| 110 along with the manifest entries |
| 111 that trigger them. |
| 112 </p> |
| 113 <p> |
| 114 <table> |
| 115 <tr> |
| 116 <th>Warning message</th> <th>Manifest entry that causes&nb
sp;it</th> <th>Notes</th> |
| 117 </tr> |
| 118 <tr> |
| 119 <td style="font-weight:bold"> |
| 120 Access all data on your computer and the websites you visit |
| 121 </td> |
| 122 <td> |
| 123 "plugins" |
| 124 </td> |
| 125 <td> |
| 126 The "plugins" permission is required by |
| 127 <a href="npapi.html">NPAPI plugins</a>. |
| 128 </td> |
| 129 </tr> |
| 130 <tr> |
| 131 <td style="font-weight:bold"> |
| 132 Read and modify your bookmarks |
| 133 </td> |
| 134 <td> |
| 135 "bookmarks" permission |
| 136 </td> |
| 137 <td> |
| 138 The "bookmarks" permission is required by the |
| 139 <a href="bookmarks.html"><code>chrome.bookmarks</code></a> module. |
| 140 </td> |
| 141 </tr> |
| 142 <tr> |
| 143 <td style="font-weight:bold"> |
| 144 Read and modify your browsing history |
| 145 </td> |
| 146 <td> |
| 147 "history" permission |
| 148 </td> |
| 149 <td> |
| 150 <p> |
| 151 The "history" permission is required by |
| 152 <a href="history.html"><code>chrome.history</code></a>. |
| 153 </p> |
| 154 </td> |
| 155 </tr> |
| 156 <tr> |
| 157 <td style="font-weight:bold"> |
| 158 Access your tabs and browsing activity |
| 159 </td> |
| 160 <td> |
| 161 Any of the following: |
| 162 <ul> |
| 163 <li> "tabs" permission </li> |
| 164 <li> "webNavigation" permission </li> |
| 165 </ul> |
| 166 </td> |
| 167 <td> |
| 168 <p> |
| 169 The "tabs" permission is required by the |
| 170 <a href="tabs.html"><code>chrome.tabs</code></a> and |
| 171 <a href="windows.html"><code>chrome.windows</code></a> modules. |
| 172 </p> |
| 173 <p> |
| 174 The "webNavigation" permission is required by the |
| 175 <a href="webNavigation.html"><code>chrome.webNavigation</code></a> module. |
| 176 </p> |
| 177 </td> |
| 178 </tr> |
| 179 <tr> |
| 180 <td style="font-weight:bold"> |
| 181 Manipulate settings that specify whether websites can use features such as c
ookies, JavaScript, and plug-ins |
| 182 </td> |
| 183 <td> |
| 184 "contentSettings" permission |
| 185 </td> |
| 186 <td> |
| 187 <p> |
| 188 The "contentSettings" permission is required by |
| 189 <a href="contentSettings.html"><code>chrome.contentSettings</code></a>. |
| 190 </p> |
| 191 </td> |
| 192 </tr> |
| 193 <tr> |
| 194 <td style="font-weight:bold"> |
| 195 Access your data on all websites |
| 196 </td> |
| 197 <td> |
| 198 Any of the following: |
| 199 <ul> |
| 200 <li> "debugger" permission </li> |
| 201 <li> "proxy" permission </li> |
| 202 <li> A match pattern in the "permissions" field |
| 203 that matches all hosts </li> |
| 204 <li> A "content_scripts" field with a "matches" entry |
| 205 that matches all hosts </li> |
| 206 <li> "devtools_page" </li> |
| 207 </ul> |
| 208 </td> |
| 209 <td> |
| 210 <p> |
| 211 The "debugger" permission is required by the experimental |
| 212 <a href="experimental.debugger.html">debugger</a> module. |
| 213 </p> |
| 214 <p> |
| 215 The "proxy" permission is required by the |
| 216 <a href="proxy.html"><code>chrome.proxy</code></a> module. |
| 217 </p> |
| 218 <p> |
| 219 Any of the following URLs match all hosts: |
| 220 </p> |
| 221 <ul> |
| 222 <li> <code>http://*/*</code> </li> |
| 223 <li> <code>https://*/*</code> </li> |
| 224 <li> <code>*://*/*</code> </li> |
| 225 <li> <code><all_urls></code> </li> |
| 226 </ul> |
| 227 </td> |
| 228 </tr> |
| 229 <tr> |
| 230 <td style="font-weight:bold"> |
| 231 Access your data on <em>{list of websites}</em> |
| 232 </td> |
| 233 <td> |
| 234 A match pattern in the "permissions" field |
| 235 that specifies one or more hosts, |
| 236 but not all hosts |
| 237 </td> |
| 238 <td> |
| 239 <p> |
| 240 Up to 3 sites are listed by name. |
| 241 Subdomains aren't treated specially. |
| 242 For example, <code>a.com</code> and <code>b.a.com</code> |
| 243 are listed as different sites. |
| 244 </p> |
| 245 <p> |
| 246 On autoupdate, |
| 247 the user sees a permission warning |
| 248 if the extension adds or changes sites. |
| 249 For example, going from <code>a.com,b.com</code> |
| 250 to <code>a.com,b.com,c.com</code> |
| 251 triggers a warning. |
| 252 Going from <code>b.a.com</code> |
| 253 to <code>a.com</code>, |
| 254 or vice versa, |
| 255 also triggers a warning. |
| 256 </p> |
| 257 </td> |
| 258 </tr> |
| 259 <tr> |
| 260 <td style="font-weight:bold"> |
| 261 Access the content of pages you visit |
| 262 </td> |
| 263 <td> |
| 264 "pageCapture" permission |
| 265 </td> |
| 266 <td> |
| 267 The "pageCapture" permission is required by the |
| 268 <a href="pageCapture.html"><code>chrome.pageCapture</code></a> module. |
| 269 </td> |
| 270 </tr> |
| 271 <tr> |
| 272 <td style="font-weight:bold"> |
| 273 Manage your apps, extensions, and themes |
| 274 </td> |
| 275 <td> |
| 276 "management" permission |
| 277 </td> |
| 278 <td> |
| 279 The "management" permission is required by the |
| 280 <a href="management.html"><code>chrome.management</code></a> module. |
| 281 </td> |
| 282 </tr> |
| 283 <tr> |
| 284 <td style="font-weight:bold"> |
| 285 Detect your physical location |
| 286 </td> |
| 287 <td> |
| 288 "geolocation" permission |
| 289 </td> |
| 290 <td> |
| 291 Allows the extension to use the proposed HTML5 |
| 292 <a href="http://dev.w3.org/geo/api/spec-source.html">geolocation API</a> |
| 293 without prompting the user for permission. |
| 294 </td> |
| 295 </tr> |
| 296 <tr> |
| 297 <td style="font-weight:bold"> |
| 298 Access data you copy and paste |
| 299 </td> |
| 300 <td> |
| 301 "clipboardRead" permission |
| 302 </td> |
| 303 <td> |
| 304 Allows the extension to use the following editing commands with |
| 305 <code>document.execCommand()</code>: |
| 306 <ul> |
| 307 <li> <code>"copy"</code> </li> |
| 308 <li> <code>"cut"</code> </li> |
| 309 </ul> |
| 310 </td> |
| 311 </tr> |
| 312 <tr> |
| 313 <td style="font-weight:bold"> |
| 314 Manipulate privacy-related settings |
| 315 </td> |
| 316 <td> |
| 317 "privacy" permission |
| 318 </td> |
| 319 <td> |
| 320 The "privacy" permission is required by the |
| 321 <a href="privacy.html"><code>chrome.privacy</code></a> module. |
| 322 </td> |
| 323 </tr> |
| 324 <tr> |
| 325 <td style="font-weight:bold"> |
| 326 Access all text spoken using synthesized speech |
| 327 </td> |
| 328 <td> |
| 329 "ttsEngine" permission |
| 330 </td> |
| 331 <td> |
| 332 The "ttsEngine" permission is required by the |
| 333 <a href="ttsEngine.html"><code>chrome.ttsEngine</code></a> module. |
| 334 </td> |
| 335 </tr> |
| 336 </table> |
| 337 </p> |
| 338 <h2 id="nowarning"> Permissions that don't cause warnings </h2> |
| 339 <p> |
| 340 The following permissions don't result in a warning: |
| 341 </p> |
| 342 <ul> |
| 343 <li>"browsingData"</li> |
| 344 <li>"chrome://favicon/"</li> |
| 345 <li>"clipboardWrite"</li> |
| 346 <li>"contextMenus"</li> |
| 347 <li>"cookies"</li> |
| 348 <li>"experimental"</li> |
| 349 <li>"idle"</li> |
| 350 <li>"notifications"</li> |
| 351 <li>"storage"</li> |
| 352 <li>"unlimitedStorage"</li> |
| 353 <li>"webRequest"</li> |
| 354 <li>"webRequestBlocking"</li> |
| 355 </ul> |
| 356 <h2 id="test"> Testing permission warnings </h2> |
| 357 <p> |
| 358 If you'd like to see exactly which warnings your users will get, |
| 359 <a href="packaging.html">package your extension</a> |
| 360 into a <code>.crx</code> file, |
| 361 and install it. |
| 362 </p> |
| 363 <p> |
| 364 To see the warnings users will get when your extension is autoupdated, |
| 365 you can go to a little more trouble |
| 366 and set up an autoupdate server. |
| 367 To do this, first create an update manifest |
| 368 and point to it from your extension, |
| 369 using the "update_url" key |
| 370 (see <a href="autoupdate.html">Autoupdating</a>). |
| 371 Next, <a href="packaging.html">package the extension</a> |
| 372 into a new <code>.crx</code> file, |
| 373 and install the app from this <code>.crx</code> file. |
| 374 Now, change the extension's manifest to contain the new permissions, |
| 375 and <a href="packaging.html#update">repackage the extension</a>. |
| 376 Finally, update the extension |
| 377 (and all other extensions that have outstanding updates) |
| 378 by clicking the <b>chrome://extensions</b> page's |
| 379 <b>Update extensions now</b> button. |
| 380 </p> |
| 381 <h2 id="api">API</h2> |
| 382 <p> |
| 383 You can get a list of permission warnings for any manifest with |
| 384 <a href="management.html#method-getPermissionWarnings">chrome.management.getPerm
issionWarnings()</a>. |
| 385 </p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src