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