notifications.html revision 4a5e2dc747d50c653511c68ccb2cfbfb740bd5a7
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>Desktop Notifications - 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 <!-- FUNCTION PARAMETERS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 </div> <!-- /VALUE --> 90 91 <div id="functionParametersTemplate"> 92 <h5>Parameters</h5> 93 <dl> 94 <div> 95 <div> 96 </div> 97 </div> 98 </dl> 99 </div> 100 </div> <!-- /SUBTEMPLATES --> 101 102 <a id="top"></a> 103 <div id="skipto"> 104 <a href="#gc-pagecontent">Skip to page content</a> 105 <a href="#gc-toc">Skip to main navigation</a> 106 </div> 107 <!-- API HEADER --> 108 <table id="header" width="100%" cellspacing="0" border="0"> 109 <tbody><tr> 110 <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> 111 <td valign="middle" width="100%" style="padding-left:0.6em;"> 112 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 113 <div id="gsc-search-box"> 114 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 115 <input type="hidden" name="ie" value="UTF-8"> 116 <input type="text" name="q" value="" size="55"> 117 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 118 <br> 119 <span class="greytext">e.g. "page action" or "tabs"</span> 120 </div> 121 </form> 122 123 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 124 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 125 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 126 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 127 </td> 128 </tr> 129 </tbody></table> 130 131 <div id="codesiteContent" class=""> 132 133 <a id="gc-topnav-anchor"></a> 134 <div id="gc-topnav"> 135 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 136 <ul id="home" class="gc-topnav-tabs"> 137 <li id="home_link"> 138 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 139 </li> 140 <li id="docs_link"> 141 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 142 </li> 143 <li id="faq_link"> 144 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 145 </li> 146 <li id="samples_link"> 147 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 148 </li> 149 <li id="group_link"> 150 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 151 </li> 152 </ul> 153 </div> <!-- end gc-topnav --> 154 155 <div class="g-section g-tpl-170"> 156 <!-- SIDENAV --> 157 <div class="g-unit g-first" id="gc-toc"> 158 <ul> 159 <li><a href="getstarted.html">Getting Started</a></li> 160 <li><a href="overview.html">Overview</a></li> 161 <li><a href="whats_new.html">What's New?</a></li> 162 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 163 <ul> 164 <li>Browser UI 165 <ul> 166 <li><a href="browserAction.html">Browser Actions</a></li> 167 <li><a href="contextMenus.html">Context Menus</a></li> 168 <li class="leftNavSelected">Desktop Notifications</li> 169 <li><a href="options.html">Options Pages</a></li> 170 <li><a href="override.html">Override Pages</a></li> 171 <li><a href="pageAction.html">Page Actions</a></li> 172 <li><a href="themes.html">Themes</a></li> 173 </ul> 174 </li> 175 <li>Browser Interaction 176 <ul> 177 <li><a href="bookmarks.html">Bookmarks</a></li> 178 <li><a href="cookies.html">Cookies</a></li> 179 <li><a href="events.html">Events</a></li> 180 <li><a href="history.html">History</a></li> 181 <li><a href="management.html">Management</a></li> 182 <li><a href="tabs.html">Tabs</a></li> 183 <li><a href="windows.html">Windows</a></li> 184 </ul> 185 </li> 186 <li>Implementation 187 <ul> 188 <li><a href="a11y.html">Accessibility</a></li> 189 <li><a href="background_pages.html">Background Pages</a></li> 190 <li><a href="content_scripts.html">Content Scripts</a></li> 191 <li><a href="xhr.html">Cross-Origin XHR</a></li> 192 <li><a href="idle.html">Idle</a></li> 193 <li><a href="i18n.html">Internationalization</a></li> 194 <li><a href="messaging.html">Message Passing</a></li> 195 <li><a href="npapi.html">NPAPI Plugins</a></li> 196 </ul> 197 </li> 198 <li>Finishing 199 <ul> 200 <li><a href="hosting.html">Hosting</a></li> 201 <li><a href="external_extensions.html">Other Deployment Options</a></li> 202 </ul> 203 </li> 204 </ul> 205 </li> 206 <li><h2><a href="tutorials.html">Tutorials</a></h2> 207 <ul> 208 <li><a href="tut_debugging.html">Debugging</a></li> 209 <li><a href="tut_analytics.html">Google Analytics</a></li> 210 <li><a href="tut_oauth.html">OAuth</a></li> 211 </ul> 212 </li> 213 <li><h2>Reference</h2> 214 <ul> 215 <li>Formats 216 <ul> 217 <li><a href="manifest.html">Manifest Files</a></li> 218 <li><a href="match_patterns.html">Match Patterns</a></li> 219 <!-- <li>Packages (.crx)</li> --> 220 </ul> 221 </li> 222 <li><a href="api_index.html">chrome.* APIs</a></li> 223 <li><a href="api_other.html">Other APIs</a></li> 224 </ul> 225 </li> 226 <li><h2><a href="samples.html">Samples</a></h2></li> 227 <div class="line"> </div> 228 <li><h2>More</h2> 229 <ul> 230 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 231 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Installable Web Apps</a></li> 232 <li><a href="themes.html">Themes</a></li> 233 </ul> 234 </li> 235 </ul> 236 </div> 237 <script> 238 initToggles(); 239 </script> 240 241 <div class="g-unit" id="gc-pagecontent"> 242 <div id="pageTitle"> 243 <h1 class="page_title">Desktop Notifications</h1> 244 </div> 245 <!-- TABLE OF CONTENTS --> 246 <div id="toc"> 247 <h2>Contents</h2> 248 <ol> 249 <li> 250 <a href="#manifest">Manifest</a> 251 <ol> 252 <li style="display: none; "> 253 <a>h3Name</a> 254 </li> 255 </ol> 256 </li><li> 257 <a href="#communication">Communicating with other views</a> 258 <ol> 259 <li style="display: none; "> 260 <a>h3Name</a> 261 </li> 262 </ol> 263 </li><li> 264 <a href="#examples"> Examples </a> 265 <ol> 266 <li style="display: none; "> 267 <a>h3Name</a> 268 </li> 269 </ol> 270 </li><li> 271 <a href="#api">API</a> 272 <ol> 273 <li style="display: none; "> 274 <a>h3Name</a> 275 </li> 276 </ol> 277 </li> 278 <li style="display: none; "> 279 <a href="#apiReference">API reference</a> 280 <ol> 281 <li> 282 <a href="#properties">Properties</a> 283 <ol> 284 <li> 285 <a href="#property-anchor">propertyName</a> 286 </li> 287 </ol> 288 </li> 289 <li> 290 <a href="#methods">Methods</a> 291 <ol> 292 <li> 293 <a href="#method-anchor">methodName</a> 294 </li> 295 </ol> 296 </li> 297 <li> 298 <a href="#events">Events</a> 299 <ol> 300 <li> 301 <a href="#event-anchor">eventName</a> 302 </li> 303 </ol> 304 </li> 305 <li> 306 <a href="#types">Types</a> 307 <ol> 308 <li> 309 <a href="#id-anchor">id</a> 310 </li> 311 </ol> 312 </li> 313 </ol> 314 </li> 315 </ol> 316 </div> 317 <!-- /TABLE OF CONTENTS --> 318 319 <!-- Standard content lead-in for experimental API pages --> 320 <p id="classSummary" style="display: none; "> 321 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 322 </p> 323 324 <!-- STATIC CONTENT PLACEHOLDER --> 325 <div id="static"><div id="pageData-name" class="pageData">Desktop Notifications</div> 326<div id="pageData-showTOC" class="pageData">true</div> 327 328<!-- BEGIN AUTHORED CONTENT --> 329<p> 330Use desktop notifications to notify users that something 331important has happened. 332Notifications appear outside the browser window. 333As the following snapshots show, 334the details of how notifications look 335and where they're shown depend on the platform. 336</p> 337 338<img src="images/notification-windows.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Microsoft Windows"> 339<img src="images/notification-mac.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Mac OS X"> 340<img src="images/notification-linux.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Ubuntu Linux"> 341 342<p> 343You create the notification window 344using a bit of JavaScript and, optionally, 345an HTML page packaged inside your extension. 346</p> 347 348 349<h2 id="manifest">Manifest</h2> 350 351<p> 352You can request the notification permission 353in the <a href="manifest.html">extension manifest</a>, 354like this: 355</p> 356 357<pre>{ 358 "name": "My extension", 359 ... 360<b> "permissions": [ 361 "notifications" 362 ]</b>, 363 ... 364}</pre> 365 366<p class="note"> 367<b>Note:</b> Extensions that declare 368the <code>notifications</code> permission 369are always allowed to create notifications. 370There is no need to call 371<code>webkitNotifications.checkPermission()</code>. 372</p> 373 374<h2 id="communication">Communicating with other views</h2> 375 376<p> 377You can communicate between a notification 378and other views in your extension using 379<a href="extension.html#method-getBackgroundPage">getBackgroundPage()</a> and 380<a href="extension.html#method-getViews">getViews()</a>. For example: 381</p> 382 383<pre>// Inside a notification... 384chrome.extension.getBackgroundPage().doThing(); 385 386// From the background page... 387chrome.extension.getViews({type:"notification"}).forEach(function(win) { 388 win.doOtherThing(); 389}); 390</pre> 391 392 393<h2 id="examples"> Examples </h2> 394 395<p> 396You can find a simple example 397of using notifications in the 398<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/notifications/">examples/api/notifications</a> 399directory. 400For other examples 401and for help in viewing the source code, 402see <a href="samples.html">Samples</a>. 403</p> 404 405<p> 406Also see html5rocks.com's 407<a href="http://www.html5rocks.com/tutorials/notifications/quick/">notifications tutorial</a>. 408Ignore the permission-related code; 409it's unnecessary if you declare the "notifications" permission. 410</p> 411 412<h2 id="api">API</h2> 413 414<p> 415The desktop notification API for extensions 416is the same one that 417is available to normal web pages. 418As the following code shows, 419you first create either a simple text notification 420or an HTML notification, 421and then you show the notification. 422</p> 423 424<pre>// Create a simple text notification: 425var notification = webkitNotifications.createNotification( 426 '48.png', // icon url - can be relative 427 'Hello!', // notification title 428 'Lorem ipsum...' // notification body text 429); 430 431// Or create an HTML notification: 432var notification = webkitNotifications.createHTMLNotification( 433 'notification.html' // html url - can be relative 434); 435 436// Then show the notification. 437notification.show(); 438</pre> 439 440<p>For complete API details, 441see the <a href="http://dev.chromium.org/developers/design-documents/desktop-notifications/api-specification">Desktop notifications draft specification</a>.</p> 442 443<!-- END AUTHORED CONTENT --> 444</div> 445 446 <!-- API PAGE --> 447 <div class="apiPage" style="display: none; "> 448 <a name="apiReference"></a> 449 <h2>API reference: chrome.apiname </h2> 450 451 <!-- PROPERTIES --> 452 <div class="apiGroup"> 453 <a name="properties"></a> 454 <h3 id="properties">Properties</h3> 455 456 <div> 457 <a></a> 458 <h4>getLastError</h4> 459 <div class="summary"> 460 <!-- Note: intentionally longer 80 columns --> 461 <span>chrome.extension</span><span>lastError</span> 462 </div> 463 <div> 464 </div> 465 </div> 466 467 </div> <!-- /apiGroup --> 468 469 <!-- METHODS --> 470 <div class="apiGroup" id="methods"> 471 <a name="methods"></a> 472 <h3>Methods</h3> 473 474 <!-- iterates over all functions --> 475 <div class="apiItem"> 476 <a></a> <!-- method-anchor --> 477 <h4>method name</h4> 478 479 <div class="summary"><span>void</span> 480 <!-- Note: intentionally longer 80 columns --> 481 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 482 <var><span></span></var></span>)</div> 483 484 <div class="description"> 485 <p class="todo">Undocumented.</p> 486 <p> 487 A description from the json schema def of the function goes here. 488 </p> 489 490 <!-- PARAMETERS --> 491 <h4>Parameters</h4> 492 <dl> 493 <div> 494 <div> 495 </div> 496 </div> 497 </dl> 498 499 <!-- RETURNS --> 500 <h4>Returns</h4> 501 <dl> 502 <div> 503 <div> 504 </div> 505 </div> 506 </dl> 507 508 <!-- CALLBACK --> 509 <div> 510 <div> 511 <h4>Callback function</h4> 512 <p> 513 The callback <em>parameter</em> should specify a function 514 that looks like this: 515 </p> 516 <p> 517 If you specify the <em>callback</em> parameter, it should 518 specify a function that looks like this: 519 </p> 520 521 <!-- Note: intentionally longer 80 columns --> 522 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 523 <dl> 524 <div> 525 <div> 526 </div> 527 </div> 528 </dl> 529 </div> 530 </div> 531 532 <!-- MIN_VERSION --> 533 <p> 534 This function was added in version <b><span></span></b>. 535 If you require this function, the manifest key 536 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 537 can ensure that your extension won't be run in an earlier browser version. 538 </p> 539 </div> <!-- /description --> 540 541 </div> <!-- /apiItem --> 542 543 </div> <!-- /apiGroup --> 544 545 <!-- EVENTS --> 546 <div class="apiGroup"> 547 <a name="events"></a> 548 <h3 id="events">Events</h3> 549 550 <!-- iterates over all events --> 551 <div class="apiItem"> 552 <a></a> 553 <h4>event name</h4> 554 555 <div class="summary"> 556 <!-- Note: intentionally longer 80 columns --> 557 <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>); 558 </div> 559 560 <div class="description"> 561 <p class="todo">Undocumented.</p> 562 <p> 563 A description from the json schema def of the event goes here. 564 </p> 565 566 <!-- PARAMETERS --> 567 <h4>Parameters</h4> 568 <dl> 569 <div> 570 <div> 571 </div> 572 </div> 573 </dl> 574 575 </div> <!-- /decription --> 576 577 </div> <!-- /apiItem --> 578 579 </div> <!-- /apiGroup --> 580 581 <!-- TYPES --> 582 <div class="apiGroup"> 583 <a name="types"></a> 584 <h3 id="types">Types</h3> 585 586 <!-- iterates over all types --> 587 <div class="apiItem"> 588 <a></a> 589 <h4>type name</h4> 590 591 <div> 592 </div> 593 594 </div> <!-- /apiItem --> 595 596 </div> <!-- /apiGroup --> 597 598 </div> <!-- /apiPage --> 599 </div> <!-- /gc-pagecontent --> 600 </div> <!-- /g-section --> 601 </div> <!-- /codesiteContent --> 602 <div id="gc-footer" --=""> 603 <div class="text"> 604 <p> 605 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 606 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 607 Attribution 3.0 License</a>, and code samples are licensed under the 608 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 609 </p> 610 <p> 611 ©2010 Google 612 </p> 613 614<!-- begin analytics --> 615<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 616<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 617 618<script type="text/javascript"> 619 // chrome doc tracking 620 try { 621 var engdocs = _gat._getTracker("YT-10763712-2"); 622 engdocs._trackPageview(); 623 } catch(err) {} 624 625 // code.google.com site-wide tracking 626 try { 627 _uacct="UA-18071-1"; 628 _uanchor=1; 629 _uff=0; 630 urchinTracker(); 631 } 632 catch(e) {/* urchinTracker not available. */} 633</script> 634<!-- end analytics --> 635 </div> 636 </div> <!-- /gc-footer --> 637 </div> <!-- /gc-container --> 638</body></html> 639
