1<h1>Overview</h1> 2 3 4<p> 5Once you've finished this page 6and the 7<a href="getstarted">Getting Started</a> tutorial, 8you'll be all set to start writing extensions. 9</p> 10 11<h2 id="what">The basics</h2> 12 13<p> 14An extension is a zipped bundle of files—HTML, 15CSS, JavaScript, images, and anything else you need—that 16adds functionality to the Google Chrome browser. 17Extensions are essentially web pages, 18and they can use all the 19<a href="api_other">APIs that the browser provides to web pages</a>, 20from XMLHttpRequest to JSON to HTML5. 21</p> 22 23<p> 24Extensions can interact with web pages or servers using 25<a href="content_scripts">content scripts</a> or 26<a href="xhr">cross-origin XMLHttpRequests</a>. 27Extensions can also interact programmatically 28with browser features such as 29<a href="bookmarks">bookmarks</a> 30and <a href="tabs">tabs</a>. 31</p> 32 33<h3 id="extension-ui">Extension UIs</h3> 34 35<p> 36Many extensions—but not Chrome Apps—add 37UI to Google Chrome in the form of 38<a href="browserAction">browser actions</a> 39or <a href="pageAction">page actions</a>. 40Each extension can have at most one browser action or page action. 41Choose a <b>browser action</b> when the extension is relevant to most pages. 42Choose a <b>page action</b> when the extension's icon 43should appear or disappear, 44depending on the page. 45</p> 46 47<table class="simple"> 48<tr> 49 <td width="33%"> 50 <img src="{{static}}/images/overview/browser-action.png" 51 width="147" height="100" 52 alt="screenshot" /> 53 </td> 54 <td width="33%"> 55 <img src="{{static}}/images/overview/page-action.png" 56 width="147" height="100" 57 alt="screenshot" /> 58 </td> 59 <td> 60 <img src="{{static}}/images/overview/browser-action-with-popup.png" 61 width="147" height="100" 62 alt="screenshot" /> 63 </td> 64</tr> 65 66<tr> 67 <td> 68 This <a href="samples#google-mail-checker">Google Mail Checker extension</a> 69 uses a <em>browser action</em> 70 (icon in the toolbar). 71 </td> 72 <td> 73 This <a href="samples#mappy">Mappy extension</a> 74 uses a <em>page action</em> 75 (icon in the address bar) 76 and <em>content script</em> 77 (code injected into a web page). 78 </td> 79 <td> 80 This <a href="samples#news-reader">News Reader extension</a> 81 features a browser action that, 82 when clicked, 83 shows a <em>popup</em>. 84 </td> 85</tr> 86</table> 87 88<p> 89Extensions (and Chrome Apps) can also present a UI in other ways, 90such as adding to the Chrome context menu, 91providing an options page, 92or using a content script that changes how pages look. 93See the <a href="devguide">Developer's Guide</a> 94for a complete list of extension features, 95with links to implementation details 96for each one. 97</p> 98 99<h2 id="files">Files</h2> 100<p> 101Each extension has the following files: 102 103</p> 104 105<ul> 106 <li>A <b>manifest file</b></li> 107 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> 108 <li><em>Optional:</em> One or more <b>JavaScript files</b></li> 109 <li><em>Optional:</em> Any other files your extension needs—for 110 example, image files</li> 111</ul> 112 113<p> 114While you're working on your extension, 115you put all these files into a single folder. 116When you distribute your extension, 117the contents of the folder are packaged into a special ZIP file 118that has a <code>.crx</code> suffix. 119If you upload your extension using the 120<a href="https://chrome.google.com/webstore/developer/dashboard">Chrome Developer Dashboard</a>, 121the <code>.crx</code> file is created for you. 122For details on distributing extensions, 123see <a href="hosting">Hosting</a>. 124</p> 125 126 127<h3 id="relative-urls">Referring to files</h3> 128 129<p> 130You can put any file you like into an extension, 131but how do you use it? 132Usually, 133you can refer to the file using a relative URL, 134just as you would in an ordinary HTML page. 135Here's an example of referring to 136a file named <code>myimage.png</code> 137that's in a subfolder named <code>images</code>. 138</p> 139 140<pre> 141<img <b>src="images/myimage.png"</b>> 142</pre> 143 144<p> 145As you might notice while you use the Google Chrome debugger, 146every file in an extension is also accessible by an absolute URL like this: 147</p> 148 149<blockquote> 150<b>chrome-extension://</b><em><extensionID></em><b>/</b><em><pathToFile></em> 151</blockquote> 152 153<p> 154In that URL, the <em><extensionID></em> is a unique identifier 155that the extension system generates for each extension. 156You can see the IDs for all your loaded extensions 157by going to the URL <b>chrome://extensions</b>. 158The <em><pathToFile></em> is the location of the file 159under the extension's top folder; 160it's the same as the relative URL. 161</p> 162 163<p> 164While you're working on an extension 165(before it's packaged), 166the extension ID can change. 167Specifically, the ID of an unpacked extension will change 168if you load the extension from a different directory; 169the ID will change again when you package the extension. 170If your extension's code 171needs to specify the full path to a file within the extension, 172you can use the <code>@@extension_id</code> 173<a href="i18n#overview-predefined">predefined message</a> 174to avoid hardcoding the ID during development. 175</p> 176 177<p> 178When you package an extension 179(typically, by uploading it with the dashboard), 180the extension gets a permanent ID, 181which remains the same even after you update the extension. 182Once the extension ID is permanent, 183you can change all occurrences of 184<code>@@extension_id</code> to use the real ID. 185</p> 186 187 188<h3 id="manifest">The manifest file</h3> 189 190<p> 191The manifest file, called <code>manifest.json</code>, 192gives information about the extension, 193such as the most important files 194and the capabilities that the extension might use. 195Here's a typical manifest file for a browser action 196that uses information from google.com: 197</p> 198 199<pre data-filename="manifest.json"> 200{ 201 "name": "My Extension", 202 "version": "2.1", 203 "description": "Gets information from Google.", 204 "icons": { "128": "icon_128.png" }, 205 "background": { 206 "persistent": false, 207 "scripts": ["bg.js"] 208 }, 209 "permissions": ["http://*.google.com/", "https://*.google.com/"], 210 "browser_action": { 211 "default_title": "", 212 "default_icon": "icon_19.png", 213 "default_popup": "popup.html" 214 } 215}</pre> 216 217<p> 218For details, see 219<a href="manifest">Manifest Files</a>. 220</p> 221 222<h2 id="arch">Architecture</h2> 223 224<p> 225Many extensions have a <em>background page</em>, 226an invisible page 227that holds the main logic of the extension. 228An extension can also contain other pages 229that present the extension's UI. 230If an extension needs to interact with web pages that the user loads 231(as opposed to pages that are included in the extension), 232then the extension must use a content script. 233</p> 234 235 236<h3 id="background_page">The background page</h3> 237 238<p> 239The following figure shows a browser 240that has at least two extensions installed: 241a browser action (yellow icon) 242and a page action (blue icon). 243Both the browser action and the page action 244have background pages. 245This figure shows the browser action's background page, 246which is defined by <code>background.html</code> 247and has JavaScript code that controls 248the behavior of the browser action in both windows. 249</p> 250 251<img src="{{static}}/images/overview/arch-1.gif" 252 width="232" height="168" 253 alt="Two windows and a box representing a background page (background.html). One window has a yellow icon; the other has both a yellow icon and a blue icon. The yellow icons are connected to the background page." /> 254 255<p> 256There are two types of background pages: 257<a href="background_pages">persistent background pages</a>, 258and <a href="event_pages">event pages</a>. Persistent 259background pages, as the name suggests, are always open. 260Event pages are opened and closed as needed. Unless you absolutely 261need your background page to run all the time, prefer to use 262an event page. 263</p> 264 265<!-- PENDING: Perhaps show a picture of many background page processes. 266 This could build on a figure that shows the process architecture. --> 267 268<p> 269See <a href="event_pages">Event Pages</a> 270and <a href="background_pages">Background Pages</a> 271for more details. 272</p> 273 274<h3 id="pages">UI pages</h3> 275 276<p> 277Extensions can contain ordinary HTML pages that display the extension's UI. 278For example, a browser action can have a popup, 279which is implemented by an HTML file. 280Any extension can have an options page, 281which lets users customize how the extension works. 282Another type of special page is the override page. 283And finally, you can 284use $(ref:tabs.create) 285or <code>window.open()</code> 286to display any other HTML files that are in the extension. 287</p> 288 289<p> 290The HTML pages inside an extension 291have complete access to each other's DOMs, 292and they can invoke functions on each other. 293</p> 294 295<!-- PENDING: Change the following example and figure 296to use something that's not a popup? 297(It might lead people to think that popups need background pages.) --> 298 299<p> 300The following figure shows the architecture 301of a browser action's popup. 302The popup's contents are a web page 303defined by an HTML file 304(<code>popup.html</code>). 305This extension also happens to have a background page 306(<code>background.html</code>). 307The popup doesn't need to duplicate code 308that's in the background page 309because the popup can invoke functions on the background page. 310</p> 311 312<img src="{{static}}/images/overview/arch-2.gif" 313 width="256" height="168" 314 alt="A browser window containing a browser action that's displaying a popup. The popup's HTML file (popup.html) can communicate with the extension's background page (background.html)." /> 315 316<p> 317See <a href="browserAction">Browser Actions</a>, 318<a href="options">Options</a>, 319<a href="override">Override Pages</a>, 320and the <a href="#pageComm">Communication between pages</a> section 321for more details. 322</p> 323 324 325<h3 id="contentScripts">Content scripts</h3> 326 327<p> 328If your extension needs to interact with web pages, 329then it needs a <em>content script</em>. 330A content script is some JavaScript 331that executes in the context of a page 332that's been loaded into the browser. 333Think of a content script as part of that loaded page, 334not as part of the extension it was packaged with 335(its <em>parent extension</em>). 336</p> 337 338<!-- [PENDING: Consider explaining that the reason content scripts are separated from the extension is due to chrome's multiprocess design. Something like: 339 340Each extension runs in its own process. 341To have rich interaction with a web page, however, 342the extension must be able to 343run some code in the web page's process. 344Extensions accomplish this with content scripts.] 345--> 346 347<p> 348Content scripts can read details of the web pages the browser visits, 349and they can make changes to the pages. 350In the following figure, 351the content script 352can read and modify 353the DOM for the displayed web page. 354It cannot, however, modify the DOM of its parent extension's background page. 355</p> 356 357<img src="{{static}}/images/overview/arch-3.gif" 358 width="238" height="169" 359 alt="A browser window with a browser action (controlled by background.html) and a content script (controlled by contentscript.js)." /> 360 361<p> 362Content scripts aren't completely cut off from their parent extensions. 363A content script can exchange messages with its parent extension, 364as the arrows in the following figure show. 365For example, a content script might send a message 366whenever it finds an RSS feed in a browser page. 367Or a background page might send a message 368asking a content script to change the appearance of its browser page. 369</p> 370 371<img src="{{static}}/images/overview/arch-cs.gif" 372 width="238" height="194" 373 alt="Like the previous figure, but showing more of the parent extension's files, as well as a communication path between the content script and the parent extension." /> 374 375 376 377<p> 378For more information, 379see <a href="content_scripts">Content Scripts</a>. 380</p> 381 382 383<h2 id="apis"> Using the chrome.* APIs </h2> 384 385<p> 386In addition to having access to all the APIs that web pages and apps can use, 387extensions can also use Chrome-only APIs 388(often called <em>chrome.* APIs</em>) 389that allow tight integration with the browser. 390For example, any extension or web app can use the 391standard <code>window.open()</code> method to open a URL. 392But if you want to specify which window that URL should be displayed in, 393your extension can use the Chrome-only 394$(ref:tabs.create) 395method instead. 396</p> 397 398<h3 id="sync"> Asynchronous vs. synchronous methods </h3> 399<p> 400Most methods in the chrome.* APIs are <b>asynchronous</b>: 401they return immediately, without waiting for the operation to finish. 402If you need to know the outcome of that operation, 403then you pass a callback function into the method. 404That callback is executed later (potentially <em>much</em> later), 405sometime after the method returns. 406Here's an example of the signature for an asynchronous method: 407</p> 408 409<p> 410<code> 411chrome.tabs.create(object <em>createProperties</em>, function <em>callback</em>) 412</code> 413</p> 414 415<p> 416Other chrome.* methods are <b>synchronous</b>. 417Synchronous methods never have a callback 418because they don't return until they've completed all their work. 419Often, synchronous methods have a return type. 420Consider the 421$(ref:runtime.getURL) method: 422</p> 423 424<p> 425<code> 426string chrome.runtime.getURL() 427</code> 428</p> 429 430<p> 431This method has no callback and a return type of <code>string</code> 432because it synchronously returns the URL 433and performs no other, asynchronous work. 434</p> 435 436 437<h3 id="sync-example"> Example: Using a callback </h3> 438 439<p> 440Say you want to navigate 441the user's currently selected tab to a new URL. 442To do this, you need to get the current tab's ID 443(using $(ref:tabs.query)) 444and then make that tab go to the new URL 445(using $(ref:tabs.update)). 446</p> 447 448<p> 449If <code>query()</code> were synchronous, 450you might write code like this: 451</p> 452 453<pre> 454<b>//THIS CODE DOESN'T WORK</b> 455var tab = chrome.tabs.query({'active': true}); <b>//WRONG!!!</b> 456chrome.tabs.update(tab.id, {url:newUrl}); 457someOtherFunction(); 458</pre> 459 460<p> 461That approach fails 462because <code>query()</code> is asynchronous. 463It returns without waiting for its work to complete, 464and it doesn't even return a value 465(although some asynchronous methods do). 466You can tell that <code>query()</code> is asynchronous 467by the <em>callback</em> parameter in its signature: 468 469<p> 470<code> 471chrome.tabs.query(object <em>queryInfo</em>, function <em>callback</em>) 472</code> 473</p> 474 475<p> 476To fix the preceding code, 477you must use that callback parameter. 478The following code shows 479how to define a callback function 480that gets the results from <code>query()</code> 481(as a parameter named <code>tab</code>) 482and calls <code>update()</code>. 483</p> 484 485<pre> 486<b>//THIS CODE WORKS</b> 487chrome.tabs.query({'active': true}, <b>function(tabs) {</b> 488 chrome.tabs.update(tabs[0].id, {url: newUrl}); 489<b>}</b>); 490someOtherFunction(); 491</pre> 492 493<p> 494In this example, the lines are executed in the following order: 1, 4, 2. 495The callback function specified to <code>query()</code> is called 496(and line 2 executed) 497only after information about the currently selected tab is available, 498which is sometime after <code>query()</code> returns. 499Although <code>update()</code> is asynchronous, 500this example doesn't use its callback parameter, 501since we don't do anything about the results of the update. 502</p> 503 504 505<h3 id="chrome-more"> More details </h3> 506 507<p> 508For more information, see the 509<a href="api_index">chrome.* API docs</a> 510and watch this video: 511</p> 512 513<div class="video-container"> 514 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube.com/embed/bmxr75CV36A?rel=0" frameborder="0" allowfullscreen></iframe> 515</div> 516 517<h2 id="pageComm">Communication between pages </h2> 518 519<p> 520The HTML pages within an extension often need to communicate. 521 522Because all of an extension's pages 523execute in same process on the same thread, 524the pages can make direct function calls to each other. 525</p> 526 527<p> 528To find pages in the extension, use 529<a href="extension"><code>chrome.extension</code></a> 530methods such as 531<code>getViews()</code> and 532<code>getBackgroundPage()</code>. 533Once a page has a reference to other pages within the extension, 534the first page can invoke functions on the other pages, 535and it can manipulate their DOMs. 536</p> 537 538<h2 id="incognito"> Saving data and incognito mode </h2> 539 540<p> 541Extensions can save data using the $(ref:storage) API, 542the HTML5 <a href="http://dev.w3.org/html5/webstorage/">web storage API</a> 543(such as <code>localStorage</code>) 544or by making server requests that result in saving data. 545Whenever you want to save something, 546first consider whether it's 547from a window that's in incognito mode. 548By default, extensions don't run in incognito windows. 549You need to consider what a user expects 550from your extension 551when the browser is incognito. 552</p> 553 554<p> 555<em>Incognito mode</em> promises that the window will leave no tracks. 556When dealing with data from incognito windows, 557do your best to honor this promise. 558For example, if your extension normally 559saves browsing history to the cloud, 560don't save history from incognito windows. 561On the other hand, you can store 562your extension's settings from any window, 563incognito or not. 564</p> 565 566<p class="note"> 567<b>Rule of thumb:</b> 568If a piece of data might show where a user 569has been on the web or what the user has done, 570don't store it if it's from an incognito window. 571</p> 572 573<p> 574To detect whether a window is in incognito mode, 575check the <code>incognito</code> property of the relevant 576$(ref:tabs.Tab) or 577$(ref:windows.Window) object. 578For example: 579</p> 580 581<pre> 582function saveTabData(tab, data) { 583 if (tab.incognito) { 584 chrome.runtime.getBackgroundPage(function(bgPage) { 585 bgPage[tab.url] = data; // Persist data ONLY in memory 586 }); 587 } else { 588 localStorage[tab.url] = data; // OK to store data 589 } 590} 591</pre> 592 593 594<h2 id="now-what"> Now what? </h2> 595 596<p> 597Now that you've been introduced to extensions, 598you should be ready to write your own. 599Here are some ideas for where to go next: 600</p> 601 602<ul> 603 <li> <a href="getstarted">Tutorial: Getting Started</a> </li> 604 <li> <a href="tut_debugging">Tutorial: Debugging</a> </li> 605 <li> <a href="devguide">Developer's Guide</a> </li> 606 <li> <a href="samples">Samples</a> </li> 607 <li> <a href="http://www.youtube.com/view_play_list?p=CA101D6A85FE9D4B">Videos</a>, 608 such as 609 <a href="http://www.youtube.com/watch?v=B4M_a7xejYI&feature=PlayList&p=CA101D6A85FE9D4B&index=6">Extension Message Passing</a> 610 </li> 611</ul> 612