faq.html revision dc0f95d653279beabeb9817299e2902918ba123e
1<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 2 1) The <head> information in this page is significant, should be uniform 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 6 browser, it will be re-generated from the template, json schema and 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10--><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="/third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script> 19 <title>Frequently Asked Questions - Google Chrome Extensions - Google Code</title></head> 20 <body> <div id="gc-container" class="labs"> 21 <div id="devModeWarning"> 22 You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. 23 </div> 24 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 25 <!-- In particular, sub-templates that recurse, must be used by allowing 26 jstemplate to make a copy of the template in this section which 27 are not operated on by way of the jsskip="true" --> 28 <div style="display:none"> 29 30 <!-- VALUE --> 31 <div id="valueTemplate"> 32 <dt> 33 <var>paramName</var> 34 <em> 35 36 <!-- TYPE --> 37 <div style="display:inline"> 38 ( 39 <span class="optional">optional</span> 40 <span class="enum">enumerated</span> 41 <span id="typeTemplate"> 42 <span> 43 <a> Type</a> 44 </span> 45 <span> 46 <span> 47 array of <span><span></span></span> 48 </span> 49 <span>paramType</span> 50 <span></span> 51 </span> 52 </span> 53 ) 54 </div> 55 56 </em> 57 </dt> 58 <dd class="todo"> 59 Undocumented. 60 </dd> 61 <dd> 62 Description of this parameter from the json schema. 63 </dd> 64 <dd> 65 This parameter was added in version 66 <b><span></span></b>. 67 You must omit this parameter in earlier versions, 68 and you may omit it in any version. If you require this 69 parameter, the manifest key 70 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 71 can ensure that your extension won't be run in an earlier browser version. 72 </dd> 73 74 <!-- OBJECT PROPERTIES --> 75 <dd> 76 <dl> 77 <div> 78 <div> 79 </div> 80 </div> 81 </dl> 82 </dd> 83 84 <!-- OBJECT METHODS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 <!-- OBJECT EVENT FIELDS --> 90 <dd> 91 <div></div> 92 </dd> 93 94 <!-- FUNCTION PARAMETERS --> 95 <dd> 96 <div></div> 97 </dd> 98 99 </div> <!-- /VALUE --> 100 101 <div id="functionParametersTemplate"> 102 <h5>Parameters</h5> 103 <dl> 104 <div> 105 <div> 106 </div> 107 </div> 108 </dl> 109 </div> 110 </div> <!-- /SUBTEMPLATES --> 111 112 <a id="top"></a> 113 <div id="skipto"> 114 <a href="#gc-pagecontent">Skip to page content</a> 115 <a href="#gc-toc">Skip to main navigation</a> 116 </div> 117 <!-- API HEADER --> 118 <table id="header" width="100%" cellspacing="0" border="0"> 119 <tbody><tr> 120 <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> 121 <td valign="middle" width="100%" style="padding-left:0.6em;"> 122 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 123 <div id="gsc-search-box"> 124 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 125 <input type="hidden" name="ie" value="UTF-8"> 126 <input type="text" name="q" value="" size="55"> 127 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 128 <br> 129 <span class="greytext">e.g. "page action" or "tabs"</span> 130 </div> 131 </form> 132 133 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 134 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 135 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 136 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 137 </td> 138 </tr> 139 </tbody></table> 140 141 <div id="codesiteContent" class=""> 142 143 <a id="gc-topnav-anchor"></a> 144 <div id="gc-topnav"> 145 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 146 <ul id="home" class="gc-topnav-tabs"> 147 <li id="home_link"> 148 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 149 </li> 150 <li id="docs_link"> 151 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 152 </li> 153 <li id="faq_link"> 154 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 155 </li> 156 <li id="samples_link"> 157 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 158 </li> 159 <li id="group_link"> 160 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 161 </li> 162 </ul> 163 </div> <!-- end gc-topnav --> 164 165 <div class="g-section g-tpl-170"> 166 <!-- SIDENAV --> 167 <div class="g-unit g-first" id="gc-toc"> 168 <ul> 169 <li><a href="getstarted.html">Getting Started</a></li> 170 <li><a href="overview.html">Overview</a></li> 171 <li><a href="whats_new.html">What's New?</a></li> 172 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 173 <ul> 174 <li>Browser UI 175 <ul> 176 <li><a href="browserAction.html">Browser Actions</a></li> 177 <li><a href="contextMenus.html">Context Menus</a></li> 178 <li><a href="notifications.html">Desktop Notifications</a></li> 179 <li><a href="omnibox.html">Omnibox</a></li> 180 <li><a href="options.html">Options Pages</a></li> 181 <li><a href="override.html">Override Pages</a></li> 182 <li><a href="pageAction.html">Page Actions</a></li> 183 </ul> 184 </li> 185 <li>Browser Interaction 186 <ul> 187 <li><a href="bookmarks.html">Bookmarks</a></li> 188 <li><a href="cookies.html">Cookies</a></li> 189 <li><a href="events.html">Events</a></li> 190 <li><a href="history.html">History</a></li> 191 <li><a href="management.html">Management</a></li> 192 <li><a href="tabs.html">Tabs</a></li> 193 <li><a href="windows.html">Windows</a></li> 194 </ul> 195 </li> 196 <li>Implementation 197 <ul> 198 <li><a href="a11y.html">Accessibility</a></li> 199 <li><a href="background_pages.html">Background Pages</a></li> 200 <li><a href="content_scripts.html">Content Scripts</a></li> 201 <li><a href="xhr.html">Cross-Origin XHR</a></li> 202 <li><a href="idle.html">Idle</a></li> 203 <li><a href="i18n.html">Internationalization</a></li> 204 <li><a href="messaging.html">Message Passing</a></li> 205 <li><a href="npapi.html">NPAPI Plugins</a></li> 206 </ul> 207 </li> 208 <li>Finishing 209 <ul> 210 <li><a href="hosting.html">Hosting</a></li> 211 <li><a href="external_extensions.html">Other Deployment Options</a></li> 212 </ul> 213 </li> 214 </ul> 215 </li> 216 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 217 <li><h2><a href="tutorials.html">Tutorials</a></h2> 218 <ul> 219 <li><a href="tut_debugging.html">Debugging</a></li> 220 <li><a href="tut_analytics.html">Google Analytics</a></li> 221 <li><a href="tut_oauth.html">OAuth</a></li> 222 </ul> 223 </li> 224 <li><h2>Reference</h2> 225 <ul> 226 <li>Formats 227 <ul> 228 <li><a href="manifest.html">Manifest Files</a></li> 229 <li><a href="match_patterns.html">Match Patterns</a></li> 230 </ul> 231 </li> 232 <li><a href="permission_warnings.html">Permission Warnings</a></li> 233 <li><a href="api_index.html">chrome.* APIs</a></li> 234 <li><a href="api_other.html">Other APIs</a></li> 235 </ul> 236 </li> 237 <li><h2><a href="samples.html">Samples</a></h2></li> 238 <div class="line"> </div> 239 <li><h2>More</h2> 240 <ul> 241 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 242 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 243 <li><a href="themes.html">Themes</a></li> 244 </ul> 245 </li> 246 </ul> 247 </div> 248 <script> 249 initToggles(); 250 </script> 251 252 <div class="g-unit" id="gc-pagecontent"> 253 <div id="pageTitle"> 254 <h1 class="page_title">Frequently Asked Questions</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc" style="display: none; "> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a>h2Name</a> 262 <ol> 263 <li> 264 <a>h3Name</a> 265 </li> 266 </ol> 267 </li> 268 <li> 269 <a href="#apiReference">API reference</a> 270 <ol> 271 <li> 272 <a href="#properties">Properties</a> 273 <ol> 274 <li> 275 <a href="#property-anchor">propertyName</a> 276 </li> 277 </ol> 278 </li> 279 <li> 280 <a>Methods</a> 281 <ol> 282 <li> 283 <a href="#method-anchor">methodName</a> 284 </li> 285 </ol> 286 </li> 287 <li> 288 <a>Events</a> 289 <ol> 290 <li> 291 <a href="#event-anchor">eventName</a> 292 </li> 293 </ol> 294 </li> 295 <li> 296 <a href="#types">Types</a> 297 <ol> 298 <li> 299 <a href="#id-anchor">id</a> 300 </li> 301 </ol> 302 </li> 303 </ol> 304 </li> 305 </ol> 306 </div> 307 <!-- /TABLE OF CONTENTS --> 308 309 <!-- Standard content lead-in for experimental API pages --> 310 <p id="classSummary" style="display: none; "> 311 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 312 </p> 313 314 <!-- STATIC CONTENT PLACEHOLDER --> 315 <div id="static"><div id="pageData-name" class="pageData">Frequently Asked Questions</div> 316 317 318<!-- <div id="pageData-showTOC" class="pageData">true</div> --> 319 320<p> 321If you don't find an answer to your question here, 322try the 323<a href="http://code.google.com/chrome/webstore/faq.html">Chrome Web Store FAQ</a>, the 324<a href="http://groups.google.com/a/chromium.org/group/chromium-extensions">group</a>, or the 325<a href="http://www.google.com/support/chrome/bin/answer.py?answer=113909">gallery help</a>. 326<!-- PENDING: add a link to store help --> 327</p> 328 329<div id="faq-TOC"> 330 <h4>General</h4> 331 <ul> 332 <li><a href="#faq-gen-01">What are Google Chrome Extensions?</a></li> 333 <li><a href="#faq-dev-01">How can I set up Chrome for extension development?</a></li> 334 <li><a href="#faq-gen-02">What technologies are used to write extensions for Chrome?</a></li> 335 <li><a href="#faq-gen-03">Are extensions fetched from the web every time the browser is loaded?</a></li> 336 <li><a href="#faq-dev-14">How do I determine which version of Chrome is deployed to which channel?</a></li> 337 </ul> 338 <h4>Capabilities</h4> 339 <ul> 340 <li><a href="#faq-dev-02">Can extensions make cross-domain Ajax requests?</a></li> 341 <li><a href="#faq-dev-03">Can extensions use 3rd party web services?</a></li> 342 <li><a href="#faq-dev-07">Can extensions encode/decode JSON data?</a></li> 343 <li><a href="#faq-dev-08">Can extensions store data locally?</a></li> 344 <li><a href="#faq-dev-04">Can extensions use OAuth?</a></li> 345 <li><a href="#faq-dev-06">Can extensions load DLLs?</a></li> 346 <li><a href="#faq-dev-05">Can extensions create UI outside of the rendered web page?</a></li> 347 <li><a href="#faq-interact-chrome">Can extensions listen to clicks on Chrome tabs and navigation buttons?</a> 348 </li><li><a href="#faq-dev-11">Can two extensions communicate with each other?</a></li> 349 <li><a href="#faq-dev-13">Can extensions use Google Analytics?</a></li> 350 <li><a href="#faq-dev-15">Can extensions modify chrome:// URLs?</a></li> 351 <li><a href="#faq-open-popups">Can extensions open browser/page action popups without user interaction?</a></li> 352 <li><a href="#faq-persist-popups">Can extensions keep popups open after the user clicks away from them?</a></li> 353 <li><a href="#faq-lifecycle-events">Can extensions be notified when they are installed/uninstalled?</a></li> 354 </ul> 355 <h4>Development</h4> 356 <ul> 357 <li><a href="#faq-building-ui">How do I build a UI for my extension?</a> 358 </li><li><a href="#faq-dev-09">How much data can I store in localStorage?</a></li> 359 <li><a href="#faq-dev-10">How do I create an options menu for my application?</a></li> 360 <li><a href="#faq-dev-12">What debugging tools are available to extension developers?</a></li> 361 <li><a href="#faq-dev-16">Why do wildcard matches not work for top level domains (TLDs)?</a></li> 362 <li><a href="#faq-management">Why does the management API not fire events when my extension is installed/uninstalled?</a></li> 363 <li><a href="#faq-firstrun">How can an extension determine whether it is running for the first time?</a></li> 364 </ul> 365 <h4>Features and bugs</h4> 366 <ul> 367 <li><a href="#faq-fea-01">I think I've found a bug! How do I make sure it gets fixed?</a></li> 368 <li><a href="#faq-fea-02">I have a feature request! How can I report it?</a></li> 369 </ul> 370</div> 371 372<h2>General</h2> 373 374<h3 id="faq-gen-01">What are Google Chrome Extensions?</h3> 375<p> 376 Google Chrome Extensions are applications that run inside the 377 Chrome browser and provide additional functionality, integration with third 378 party websites or services, and customized browsing experiences. 379</p> 380 381<h3 id="faq-dev-01">How can I set up Chrome for extension development?</h3> 382<p> 383 As long as you are using a version of Chrome that supports 384 extensions, you already have everything you need to start writing an 385 extension of your own. 386 You can start by turning on Developer mode. 387 </p> 388 389 <p> 390 Click the wrench icon 391 <img src="images/toolsmenu.gif" height="29" width="29" alt="" class="nomargin"> 392 and select <b>Extensions</b> from the <b>Tools</b> menu. 393 If there's a "+" next to "Developer mode", 394 click the "+" so it turns into a "-". 395 Now you can reload extensions, 396 load an unpacked directory of files as if it were a packaged extension, 397 and more. For a complete tutorial, see 398 <a href="http://code.google.com/chrome/extensions/getstarted.html">Getting Started</a>. 399</p> 400 401<h3 id="faq-gen-02">What technologies are used to write extensions for Chrome?</h3> 402<p> 403 Extensions are written using the same standard web 404 technologies that developers use to create websites. HTML is used as a 405 content markup language, CSS is used for styling, and JavaScript for 406 scripting. Because Chrome supports HTML5 and CSS3, developers can 407 use the latest open web technologies such as canvas and CSS animations in 408 their extensions. Extensions also have access to several 409 <a href="http://code.google.com/chrome/extensions/api_other.html">JavaScript APIs</a> 410 that help perform functions like JSON encoding and interacting with the 411 browser. 412</p> 413 414 415<h3 id="faq-gen-03">Are extensions fetched from the web every time the browser is loaded?</h3> 416<p> 417 Extensions are downloaded by the Chrome browser upon install, and 418 are subsequently run off of the local disk in order to speed up 419 performance. However, if a new version of the extension is pushed online, 420 it will be automatically downloaded in the background to any users who 421 have the extension installed. Extensions may also make requests for remote 422 content at any time, in order to interact with a web service or pull new 423 content from the web. 424</p> 425 426<h3 id="faq-dev-14">How do I determine which version of Chrome is deployed to which channel?</h3> 427<p> 428 To determine which version of Chrome is currently available on each 429 of the different platforms, visit 430 <a href="http://omahaproxy.appspot.com">omahaproxy.appspot.com</a>. On that 431 site you will see data in a format similar to: 432</p> 433 434<pre>cf,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 435cf,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 436cf,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 437linux,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 438linux,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 439linux,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 440mac,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 441mac,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 442mac,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 443win,canary,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 444win,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 445win,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 446win,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 447cros,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,##### 448cros,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####</pre> 449 450<p> 451 Each line represents information about a different platform and channel 452 combination. The 453 listed platforms are <code>cf</code> (Google Chrome Frame), 454 <code>linux</code>, <code>mac</code>, <code>win</code>, and 455 <code>cros</code> (Google Chrome OS). The listed 456 channels are <code>canary</code>, <code>dev</code>, <code>beta</code>, 457 and <code>stable</code>. 458 The two four-part numbers after the channel represent the current and previous 459 versions of Chrome deployed to that platform-channel 460 combination. The rest of the information is metadata about when the releases 461 were first pushed, as well as revision numbers associated with each build. 462</p> 463 464 465<h2>Capabilities</h2> 466 467<h3 id="faq-dev-02">Can extensions make cross-domain Ajax requests?</h3> 468<p> 469 Yes. Extensions can make cross-domain requests. See 470 <a href="http://code.google.com/chrome/extensions/xhr.html">this page</a> 471 for more information. 472</p> 473 474<h3 id="faq-dev-03">Can extensions use 3rd party web services?</h3> 475<p> 476 Yes. Extensions are capable of making cross-domain Ajax 477 requests, so they can call remote APIs directly. APIs that provide data 478 in JSON format are particularly easy to use. 479</p> 480 481<h3 id="faq-dev-07">Can extensions encode/decode JSON data?</h3> 482<p> 483 Yes, because V8 (Chrome's JavaScript engine) supports 484 JSON.stringify and JSON.parse natively, you may use these functions in your 485 extensions 486 <a href="http://json.org/js.html">as described here</a> without including 487 any additional JSON libraries in your code. 488</p> 489 490<h3 id="faq-dev-08">Can extensions store data locally?</h3> 491<p> 492 Yes, extensions can use <a href="http://dev.w3.org/html5/webstorage/">localStorage</a> 493 to store string data permanently. Using Chrome's built-in JSON 494 functions, you can store complex data structures in localStorage. For 495 extensions that need to execute SQL queries on their stored data, 496 Chrome implements 497 <a href="http://dev.w3.org/html5/webdatabase/">client side SQL databases</a>, 498 which may be used as well. 499</p> 500 501<h3 id="faq-dev-04">Can extensions use OAuth?</h3> 502<p> 503 Yes, there are extensions that use OAuth to access remote data 504 APIs. Most developers find it convenient to use a 505 <a href="http://unitedheroes.net/OAuthSimple/js/OAuthSimple.js">JavaScript OAuth library</a> 506 in order to simplify the process of signing OAuth requests. 507</p> 508 509<h3 id="faq-dev-06">Can extensions load DLLs?</h3> 510<p> 511 Yes, using the <a href="npapi.html">NPAPI interface</a>. 512 Because of the possibility for abuse, though, we will review your extension 513 before hosting it in the Google Chrome Extensions Gallery 514 or Chrome Web Store. 515</p> 516 517<h3 id="faq-dev-05">Can extensions create UI outside of the rendered web page?</h3> 518<p> 519 Yes, your extension may add buttons to the Chrome browser's user interface. 520 See <a href="browserAction.html">browser actions</a> and 521 <a href="pageAction.html">page actions</a> for more information. 522</p> 523<p> 524 An extension may also create popup notifications, which exist outside of the 525 browser window. See the <a href="notifications.html">desktop 526 notifications</a> documentation for more details. 527</p> 528 529<h3 id="faq-interact-chrome">Can extensions listen to clicks on Chrome tabs and 530 navigation buttons?</h3> 531<p> 532 No. Extensions are limited to listening to the events described in the <a href="api_index.html">API documentation</a>. 533</p> 534 535<h3 id="faq-dev-11">Can two extensions communicate with each other?</h3> 536<p> 537 Yes, extensions may pass messages to other extensions. See the 538 <a href="messaging.html#external">message passing documentation</a> 539 for more information. 540</p> 541 542<h3 id="faq-dev-13">Can extensions use Google Analytics?</h3> 543<p> 544 Yes, since extensions are built just like websites, they can use 545 <a href="http://www.google.com/analytics/">Google Analytics</a> to track 546 usage. However, we strongly advise you to modify the tracking code to pull 547 an HTTPS version of the Google Analytics library. See 548 <a href="tut_analytics.html">this tutorial</a> for more information on doing 549 this. 550</p> 551 552<h3 id="faq-dev-15">Can extensions modify chrome:// URLs?</h3> 553<p> 554 No. The extensions APIs have been designed to minimize backwards 555 compatibility issues that can arise when new versions of the browser are 556 pushed. Allowing content scripts on <code>chrome://</code> 557 URLs would mean that developers would begin to rely on the DOM, CSS, and 558 JavaScript of these pages to stay the same. In the best case, these pages 559 could not be updated as quickly as they are being updated right now. 560 In the worst case, it could mean that an update to one 561 of these pages could cause an extension to break, causing key parts of the 562 browser to stop working for users of that extension. 563</p> 564 565<p> 566 The reason that <a href="override.html">replacing the content</a> 567 hosted at these URLs entirely is 568 allowed is because it forces an extension developer to implement all of the 569 functionality they want without depending on the browser's internal implementation 570 to stay the same. 571</p> 572 573<h3 id="faq-open-popups">Can extensions open browser/page action popups without 574 user interaction?</h3> 575<p> 576 No, popups can only be opened if the user clicks on the corresponding page or 577 browser action. An extension cannot open its popup programatically. 578</p> 579 580<h3 id="faq-persist-popups">Can extensions keep popups open after the user 581 clicks away from them?</h3> 582<p> 583 No, popups automatically close when the user focuses on some portion of the 584 browser outside of the popup. There is no way to keep the popup open after 585 the user has clicked away. 586</p> 587 588<h3 id="faq-lifecycle-events">Can extensions be notified when they are 589 installed/uninstalled?</h3> 590<p> 591 No, there are no events an extension can listen to in order to determine 592 whether it has been installed or uninstalled. However, an extension can 593 determine when it has been run for the first time. See <a href="#faq-firstrun">this FAQ entry</a> for information. 594</p> 595 596 597<h2>Development</h2> 598 599 600<h3 id="faq-building-ui">How do I build a UI for my extension?</h3> 601<p> 602 Extensions use HTML and CSS to define their user interfaces, so you can use 603 standard form controls to build your UI, or style the interface with CSS, 604 as you would a web page. Additionally, extensions can add 605 <a href="#faq-dev-05">some limited UI elements to Chrome itself.</a> 606</p> 607 608<h3 id="faq-dev-09">How much data can I store in localStorage?</h3> 609<p> 610 Extensions can store up to 5MB of data in localStorage. 611</p> 612 613<h3 id="faq-dev-10">How do I create an options menu for my application?</h3> 614<p> 615 You can let users set options for your extension by creating an 616 <a href="http://code.google.com/chrome/extensions/trunk/options.html">options page</a>, 617 which is a simple HTML page that will be loaded when a user clicks the 618 "options" button for your extension. This page can read and write settings 619 to localStorage, or even send options to a web server so that they can be 620 persisted across browsers. 621</p> 622 623<h3 id="faq-dev-12">What debugging tools are available to extension developers?</h3> 624<p> 625 Chrome's built-in developer tools can be used to debug extensions 626 as well as web pages. See this 627 <a href="http://code.google.com/chrome/extensions/tut_debugging.html ">tutorial on debugging extensions</a> 628 for more information. 629</p> 630 631<h3 id="faq-dev-16">Why do wildcard matches not work for top level domains 632 (TLDs)?</h3> 633<p> 634 You cannot use wildcard match patterns like <code>http://google.*/*</code> 635 to match TLDs (like <code>http://google.es</code> and 636 <code>http://google.fr</code>) due to the 637 complexity of actually restricting such a match to only the desired domains. 638</p> 639<p> 640 For the example of <code>http://google.*/*</code>, the Google domains would 641 be matched, but so would <code>http://google.someotherdomain.com</code>. 642 Additionally, many sites do not own all of the TLDs for their 643 domain. For an example, assume you want to use 644 <code>http://example.*/*</code> to match <code>http://example.com</code> and 645 <code>http://example.es</code>, but <code>http://example.net</code> is a 646 hostile site. If your extension has a bug, the hostile site could potentially 647 attack your extension in order to get access to your extension's increased 648 privileges. 649</p> 650<p> 651 You should explicitly enumerate the TLDs that you wish to run 652 your extension on. 653</p> 654 655<h3 id="faq-management">Why does the management API not fire events when my 656 extension is installed/uninstalled?</h3> 657<p> 658 The <a href="management.html">management API</a> was intended to help create 659 new tab page replacement extensions. It was not intended to fire 660 install/uninstall events for the current extension. 661</p> 662 663<h3 id="faq-firstrun">How can an extension determine whether it is running for 664 the first time?</h3> 665<p> 666 An extension can check to see whether it is running for the first time by 667 checking for the presence of a value in localStorage, and writing the value if 668 it does not exist. For example: 669</p> 670 671<pre>var firstRun = (localStorage['firstRun'] == 'true'); 672if (!firstRun) { 673 localStorage['firstRun'] = 'true'; 674}</pre> 675 676<p> 677 Note that this check should be run in a background page, not a content script. 678</p> 679 680 681<h2>Features and bugs</h2> 682 683 684<h3 id="faq-fea-01">I think I've found a bug! How do I make sure it gets 685 fixed?</h3> 686<p> 687 While developing an extension, you may find behavior that does not 688 match the extensions documentation and may be the result of a bug in 689 Chrome. The best thing to do is to make sure an appropriate issue 690 report is filed, and the Chromium team has enough information to reproduce 691 the behavior. 692</p> 693 694<p>The steps you should follow to ensure this are:</p> 695 696<ol> 697 <li> 698 Come up with a <em>minimal</em> test extension that demonstrates the issue 699 you wish to report. This extension should have as little code as possible 700 to demonstrate the bug—generally this should be 100 lines of 701 code or less. Many times, developers find that they cannot reproduce their 702 issues this way, which is a good indicator that the bug is in their own 703 code. 704 </li> 705 <li> 706 Search the issue tracker at 707 <a href="http://www.crbug.com">http://www.crbug.com</a> to see whether 708 someone has reported a similar issue. Most issues related to 709 extensions are filed under <strong>Feature=Extensions</strong>, so to 710 look for an extension bug related to the 711 chrome.tabs.executeScript function (for example), search for 712 "<code>Feature=Extensions Type=Bug chrome.tabs.executeScript</code>", 713 which will give you 714 <a href="http://code.google.com/p/chromium/issues/list?can=2&q=Feature%3DExtensions+Type%3DBug+chrome.tabs.executeScript&colspec=ID+Stars+Pri+Area+Feature+Type+Status+Summary+Modified+Owner+Mstone+OS&x=mstone&y=area&cells=tiles"> 715 this list of results</a>. 716 </li> 717 <li> 718 If you find a bug that describes your issue, click the star icon to be 719 notified when the bug receives an update. <em>Do not respond to the 720 bug to say "me too" or ask "when will this be fixed?"</em>; such updates 721 can cause hundreds of emails to be sent. Add a comment only if you have 722 information (such as a better test case or a suggested fix) that is likely 723 to be helpful. 724 </li> 725 <li> 726 If you found no appropriate bug to star, file a new issue report at 727 <a href="http://new.crbug.com">http://new.crbug.com</a>. Be as explicit 728 as possible when filling out this form: choose a descriptive title, 729 explain the steps to reproduce the bug, and describe the expected and 730 actual behavior. Attach your test example to the report and add 731 screenshots if appropriate. The easier your report makes it for others 732 to reproduce your issue, the greater chance that your bug will be fixed 733 promptly. 734 </li> 735 <li> 736 Wait for the bug to be updated. Most new bugs are triaged within a week, 737 although it can sometimes take longer for an update. <em>Do not reply 738 to the bug to ask when the issue will be fixed.</em> If your bug has not 739 been modified after two weeks, please post a message to the 740 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions/topics"> 741 discussion group</a> with a link back to your bug. 742 </li> 743 <li> 744 If you originally reported your bug on the discussion group and were 745 directed to this FAQ entry, reply to your original thread with a link 746 to the bug you starred or reported. This will make it easier for others 747 experiencing the same issue to find the correct bug. 748 </li> 749</ol> 750 751<h3 id="faq-fea-02">I have a feature request! How can I report it?</h3> 752 753<p>If you identify a feature (especially if it's related to an experimental 754 API) that could be added to improve the extension development experience, 755 make sure an appropriate request is filed in the issue tracker.</p> 756 757<p>The steps you should follow to ensure this are:</p> 758 759<ol> 760 <li> 761 Search the issue tracker at 762 <a href="http://www.crbug.com">http://www.crbug.com</a> to see whether 763 someone has requested a similar feature. Most requests related to 764 extensions are filed under <strong>Feature=Extensions</strong>, so to 765 look for an extension feature request related to keyboard shortcuts 766 (for example), search 767 for "<code>Feature=Extensions Type=Feature shortcuts</code>", 768 which will give you 769 <a href="http://code.google.com/p/chromium/issues/list?can=2&q=Feature%3DExtensions+Type%3DFeature+shortcuts&colspec=ID+Stars+Pri+Area+Feature+Type+Status+Summary+Modified+Owner+Mstone+OS&x=mstone&y=area&cells=tiles"> 770 this list of results</a>. 771 </li> 772 <li> 773 If you find a ticket that matches your request, click the star icon to be 774 notified when the bug receives an update. <em>Do not respond to the 775 bug to say "me too" or ask "when will this be implemented?"</em>; such 776 updates can cause hundreds of emails to be sent. 777 </li> 778 <li> 779 If you found no appropriate ticket to star, file a new request at 780 <a href="http://new.crbug.com">http://new.crbug.com</a>. Be as detailed 781 as possible when filling out this form: choose a descriptive title 782 and explain exactly what feature you would like and how you plan to use it. 783 </li> 784 <li> 785 Wait for the ticket to be updated. Most new requests are triaged within a 786 week, although it can sometimes take longer for an update. <em>Do not reply 787 to the ticket to ask when the feature will be added.</em> If your 788 ticket has not been modified after two weeks, please post a message to the 789 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions/topics"> 790 discussion group</a> with a link back to your request. 791 </li> 792 <li> 793 If you originally reported your request on the discussion group and were 794 directed to this FAQ entry, reply to your original thread with a link 795 to the ticket you starred or opened. This will make it easier for others 796 with the same request to find the correct ticket. 797 </li> 798</ol> 799 800</div> 801 802 <!-- API PAGE --> 803 <div class="apiPage" style="display: none; "> 804 <a name="apiReference"></a> 805 <h2>API reference: chrome.apiname </h2> 806 807 <!-- PROPERTIES --> 808 <div class="apiGroup"> 809 <a name="properties"></a> 810 <h3 id="properties">Properties</h3> 811 812 <div> 813 <a></a> 814 <h4>getLastError</h4> 815 <div class="summary"> 816 <!-- Note: intentionally longer 80 columns --> 817 <span>chrome.extension</span><span>lastError</span> 818 </div> 819 <div> 820 </div> 821 </div> 822 823 </div> <!-- /apiGroup --> 824 825 <!-- METHODS --> 826 <div id="methodsTemplate" class="apiGroup"> 827 <a></a> 828 <h3>Methods</h3> 829 830 <!-- iterates over all functions --> 831 <div class="apiItem"> 832 <a></a> <!-- method-anchor --> 833 <h4>method name</h4> 834 835 <div class="summary"><span>void</span> 836 <!-- Note: intentionally longer 80 columns --> 837 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 838 <var><span></span></var></span>)</div> 839 840 <div class="description"> 841 <p class="todo">Undocumented.</p> 842 <p> 843 A description from the json schema def of the function goes here. 844 </p> 845 846 <!-- PARAMETERS --> 847 <h4>Parameters</h4> 848 <dl> 849 <div> 850 <div> 851 </div> 852 </div> 853 </dl> 854 855 <!-- RETURNS --> 856 <h4>Returns</h4> 857 <dl> 858 <div> 859 <div> 860 </div> 861 </div> 862 </dl> 863 864 <!-- CALLBACK --> 865 <div> 866 <div> 867 <h4>Callback function</h4> 868 <p> 869 The callback <em>parameter</em> should specify a function 870 that looks like this: 871 </p> 872 <p> 873 If you specify the <em>callback</em> parameter, it should 874 specify a function that looks like this: 875 </p> 876 877 <!-- Note: intentionally longer 80 columns --> 878 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 879 <dl> 880 <div> 881 <div> 882 </div> 883 </div> 884 </dl> 885 </div> 886 </div> 887 888 <!-- MIN_VERSION --> 889 <p> 890 This function was added in version <b><span></span></b>. 891 If you require this function, the manifest key 892 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 893 can ensure that your extension won't be run in an earlier browser version. 894 </p> 895 </div> <!-- /description --> 896 897 </div> <!-- /apiItem --> 898 899 </div> <!-- /apiGroup --> 900 901 <!-- EVENTS --> 902 <div id="eventsTemplate" class="apiGroup"> 903 <a></a> 904 <h3>Events</h3> 905 <!-- iterates over all events --> 906 <div class="apiItem"> 907 <a></a> 908 <h4>event name</h4> 909 910 <div class="summary"> 911 <!-- Note: intentionally longer 80 columns --> 912 <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); 913 </div> 914 915 <div class="description"> 916 <p class="todo">Undocumented.</p> 917 <p> 918 A description from the json schema def of the event goes here. 919 </p> 920 921 <!-- PARAMETERS --> 922 <div> 923 <h4>Parameters</h4> 924 <dl> 925 <div> 926 <div> 927 </div> 928 </div> 929 </dl> 930 </div> 931 </div> <!-- /decription --> 932 933 </div> <!-- /apiItem --> 934 935 </div> <!-- /apiGroup --> 936 937 <!-- TYPES --> 938 <div class="apiGroup"> 939 <a name="types"></a> 940 <h3 id="types">Types</h3> 941 942 <!-- iterates over all types --> 943 <div class="apiItem"> 944 <a></a> 945 <h4>type name</h4> 946 947 <div> 948 </div> 949 950 </div> <!-- /apiItem --> 951 952 </div> <!-- /apiGroup --> 953 954 </div> <!-- /apiPage --> 955 </div> <!-- /gc-pagecontent --> 956 </div> <!-- /g-section --> 957 </div> <!-- /codesiteContent --> 958 <div id="gc-footer" --=""> 959 <div class="text"> 960 <p> 961 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 962 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 963 Attribution 3.0 License</a>, and code samples are licensed under the 964 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 965 </p> 966 <p> 967 ©2011 Google 968 </p> 969 970<!-- begin analytics --> 971<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 972<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 973 974<script type="text/javascript"> 975 // chrome doc tracking 976 try { 977 var engdocs = _gat._getTracker("YT-10763712-2"); 978 engdocs._trackPageview(); 979 } catch(err) {} 980 981 // code.google.com site-wide tracking 982 try { 983 _uacct="UA-18071-1"; 984 _uanchor=1; 985 _uff=0; 986 urchinTracker(); 987 } 988 catch(e) {/* urchinTracker not available. */} 989</script> 990<!-- end analytics --> 991 </div> 992 </div> <!-- /gc-footer --> 993 </div> <!-- /gc-container --> 994</body></html> 995
