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