notifications.html revision 201ade2fbba22bfb27ae029f4d23fca6ded109a0
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="omnibox.html">Omnibox</a></li> 170 <li><a href="options.html">Options Pages</a></li> 171 <li><a href="override.html">Override Pages</a></li> 172 <li><a href="pageAction.html">Page Actions</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="apps.html">Packaged Apps</a></h2></li> 207 <li><h2><a href="tutorials.html">Tutorials</a></h2> 208 <ul> 209 <li><a href="tut_debugging.html">Debugging</a></li> 210 <li><a href="tut_analytics.html">Google Analytics</a></li> 211 <li><a href="tut_oauth.html">OAuth</a></li> 212 </ul> 213 </li> 214 <li><h2>Reference</h2> 215 <ul> 216 <li>Formats 217 <ul> 218 <li><a href="manifest.html">Manifest Files</a></li> 219 <li><a href="match_patterns.html">Match Patterns</a></li> 220 </ul> 221 </li> 222 <li><a href="permission_warnings.html">Permission Warnings</a></li> 223 <li><a href="api_index.html">chrome.* APIs</a></li> 224 <li><a href="api_other.html">Other APIs</a></li> 225 </ul> 226 </li> 227 <li><h2><a href="samples.html">Samples</a></h2></li> 228 <div class="line"> </div> 229 <li><h2>More</h2> 230 <ul> 231 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 232 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 233 <li><a href="themes.html">Themes</a></li> 234 </ul> 235 </li> 236 </ul> 237 </div> 238 <script> 239 initToggles(); 240 </script> 241 242 <div class="g-unit" id="gc-pagecontent"> 243 <div id="pageTitle"> 244 <h1 class="page_title">Desktop Notifications</h1> 245 </div> 246 <!-- TABLE OF CONTENTS --> 247 <div id="toc"> 248 <h2>Contents</h2> 249 <ol> 250 <li> 251 <a href="#manifest">Manifest</a> 252 <ol> 253 <li style="display: none; "> 254 <a>h3Name</a> 255 </li> 256 </ol> 257 </li><li> 258 <a href="#communication">Communicating with other views</a> 259 <ol> 260 <li style="display: none; "> 261 <a>h3Name</a> 262 </li> 263 </ol> 264 </li><li> 265 <a href="#examples"> Examples </a> 266 <ol> 267 <li style="display: none; "> 268 <a>h3Name</a> 269 </li> 270 </ol> 271 </li><li> 272 <a href="#api">API</a> 273 <ol> 274 <li style="display: none; "> 275 <a>h3Name</a> 276 </li> 277 </ol> 278 </li> 279 <li style="display: none; "> 280 <a href="#apiReference">API reference</a> 281 <ol> 282 <li> 283 <a href="#properties">Properties</a> 284 <ol> 285 <li> 286 <a href="#property-anchor">propertyName</a> 287 </li> 288 </ol> 289 </li> 290 <li> 291 <a href="#methods">Methods</a> 292 <ol> 293 <li> 294 <a href="#method-anchor">methodName</a> 295 </li> 296 </ol> 297 </li> 298 <li> 299 <a href="#events">Events</a> 300 <ol> 301 <li> 302 <a href="#event-anchor">eventName</a> 303 </li> 304 </ol> 305 </li> 306 <li> 307 <a href="#types">Types</a> 308 <ol> 309 <li> 310 <a href="#id-anchor">id</a> 311 </li> 312 </ol> 313 </li> 314 </ol> 315 </li> 316 </ol> 317 </div> 318 <!-- /TABLE OF CONTENTS --> 319 320 <!-- Standard content lead-in for experimental API pages --> 321 <p id="classSummary" style="display: none; "> 322 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 323 </p> 324 325 <!-- STATIC CONTENT PLACEHOLDER --> 326 <div id="static"><div id="pageData-name" class="pageData">Desktop Notifications</div> 327<div id="pageData-showTOC" class="pageData">true</div> 328 329<!-- BEGIN AUTHORED CONTENT --> 330<p> 331Use desktop notifications to notify users that something 332important has happened. 333Notifications appear outside the browser window. 334As the following snapshots show, 335the details of how notifications look 336and where they're shown depend on the platform. 337</p> 338 339<img src="images/notification-windows.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Microsoft Windows"> 340<img src="images/notification-mac.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Mac OS X"> 341<img src="images/notification-linux.png" width="28%" style="margin:2em 0.5em 1em; border:1px solid black;" alt="Notifications on Ubuntu Linux"> 342 343<p> 344You create the notification window 345using a bit of JavaScript and, optionally, 346an HTML page packaged inside your extension. 347</p> 348 349 350<h2 id="manifest">Manifest</h2> 351 352<p> 353You can request the notification permission 354in the <a href="manifest.html">extension manifest</a>, 355like this: 356</p> 357 358<pre>{ 359 "name": "My extension", 360 ... 361<b> "permissions": [ 362 "notifications" 363 ]</b>, 364 ... 365}</pre> 366 367<p class="note"> 368<b>Note:</b> Extensions that declare 369the <code>notifications</code> permission 370are always allowed to create notifications. 371There is no need to call 372<code>webkitNotifications.checkPermission()</code>. 373</p> 374 375<h2 id="communication">Communicating with other views</h2> 376 377<p> 378You can communicate between a notification 379and other views in your extension using 380<a href="extension.html#method-getBackgroundPage">getBackgroundPage()</a> and 381<a href="extension.html#method-getViews">getViews()</a>. For example: 382</p> 383 384<pre>// Inside a notification... 385chrome.extension.getBackgroundPage().doThing(); 386 387// From the background page... 388chrome.extension.getViews({type:"notification"}).forEach(function(win) { 389 win.doOtherThing(); 390}); 391</pre> 392 393 394<h2 id="examples"> Examples </h2> 395 396<p> 397You can find a simple example 398of using notifications in the 399<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/notifications/">examples/api/notifications</a> 400directory. 401For other examples 402and for help in viewing the source code, 403see <a href="samples.html">Samples</a>. 404</p> 405 406<p> 407Also see html5rocks.com's 408<a href="http://www.html5rocks.com/tutorials/notifications/quick/">notifications tutorial</a>. 409Ignore the permission-related code; 410it's unnecessary if you declare the "notifications" permission. 411</p> 412 413<h2 id="api">API</h2> 414 415<p> 416The desktop notification API for extensions 417is the same one that 418is available to normal web pages. 419As the following code shows, 420you first create either a simple text notification 421or an HTML notification, 422and then you show the notification. 423</p> 424 425<pre>// Create a simple text notification: 426var notification = webkitNotifications.createNotification( 427 '48.png', // icon url - can be relative 428 'Hello!', // notification title 429 'Lorem ipsum...' // notification body text 430); 431 432// Or create an HTML notification: 433var notification = webkitNotifications.createHTMLNotification( 434 'notification.html' // html url - can be relative 435); 436 437// Then show the notification. 438notification.show(); 439</pre> 440 441<p>For complete API details, 442see the <a href="http://dev.chromium.org/developers/design-documents/desktop-notifications/api-specification">Desktop notifications draft specification</a>.</p> 443 444<!-- END AUTHORED CONTENT --> 445</div> 446 447 <!-- API PAGE --> 448 <div class="apiPage" style="display: none; "> 449 <a name="apiReference"></a> 450 <h2>API reference: chrome.apiname </h2> 451 452 <!-- PROPERTIES --> 453 <div class="apiGroup"> 454 <a name="properties"></a> 455 <h3 id="properties">Properties</h3> 456 457 <div> 458 <a></a> 459 <h4>getLastError</h4> 460 <div class="summary"> 461 <!-- Note: intentionally longer 80 columns --> 462 <span>chrome.extension</span><span>lastError</span> 463 </div> 464 <div> 465 </div> 466 </div> 467 468 </div> <!-- /apiGroup --> 469 470 <!-- METHODS --> 471 <div class="apiGroup" id="methods"> 472 <a name="methods"></a> 473 <h3>Methods</h3> 474 475 <!-- iterates over all functions --> 476 <div class="apiItem"> 477 <a></a> <!-- method-anchor --> 478 <h4>method name</h4> 479 480 <div class="summary"><span>void</span> 481 <!-- Note: intentionally longer 80 columns --> 482 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 483 <var><span></span></var></span>)</div> 484 485 <div class="description"> 486 <p class="todo">Undocumented.</p> 487 <p> 488 A description from the json schema def of the function goes here. 489 </p> 490 491 <!-- PARAMETERS --> 492 <h4>Parameters</h4> 493 <dl> 494 <div> 495 <div> 496 </div> 497 </div> 498 </dl> 499 500 <!-- RETURNS --> 501 <h4>Returns</h4> 502 <dl> 503 <div> 504 <div> 505 </div> 506 </div> 507 </dl> 508 509 <!-- CALLBACK --> 510 <div> 511 <div> 512 <h4>Callback function</h4> 513 <p> 514 The callback <em>parameter</em> should specify a function 515 that looks like this: 516 </p> 517 <p> 518 If you specify the <em>callback</em> parameter, it should 519 specify a function that looks like this: 520 </p> 521 522 <!-- Note: intentionally longer 80 columns --> 523 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 524 <dl> 525 <div> 526 <div> 527 </div> 528 </div> 529 </dl> 530 </div> 531 </div> 532 533 <!-- MIN_VERSION --> 534 <p> 535 This function was added in version <b><span></span></b>. 536 If you require this function, the manifest key 537 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 538 can ensure that your extension won't be run in an earlier browser version. 539 </p> 540 </div> <!-- /description --> 541 542 </div> <!-- /apiItem --> 543 544 </div> <!-- /apiGroup --> 545 546 <!-- EVENTS --> 547 <div class="apiGroup"> 548 <a name="events"></a> 549 <h3 id="events">Events</h3> 550 551 <!-- iterates over all events --> 552 <div class="apiItem"> 553 <a></a> 554 <h4>event name</h4> 555 556 <div class="summary"> 557 <!-- Note: intentionally longer 80 columns --> 558 <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>); 559 </div> 560 561 <div class="description"> 562 <p class="todo">Undocumented.</p> 563 <p> 564 A description from the json schema def of the event goes here. 565 </p> 566 567 <!-- PARAMETERS --> 568 <h4>Parameters</h4> 569 <dl> 570 <div> 571 <div> 572 </div> 573 </div> 574 </dl> 575 576 </div> <!-- /decription --> 577 578 </div> <!-- /apiItem --> 579 580 </div> <!-- /apiGroup --> 581 582 <!-- TYPES --> 583 <div class="apiGroup"> 584 <a name="types"></a> 585 <h3 id="types">Types</h3> 586 587 <!-- iterates over all types --> 588 <div class="apiItem"> 589 <a></a> 590 <h4>type name</h4> 591 592 <div> 593 </div> 594 595 </div> <!-- /apiItem --> 596 597 </div> <!-- /apiGroup --> 598 599 </div> <!-- /apiPage --> 600 </div> <!-- /gc-pagecontent --> 601 </div> <!-- /g-section --> 602 </div> <!-- /codesiteContent --> 603 <div id="gc-footer" --=""> 604 <div class="text"> 605 <p> 606 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 607 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 608 Attribution 3.0 License</a>, and code samples are licensed under the 609 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 610 </p> 611 <p> 612 ©2010 Google 613 </p> 614 615<!-- begin analytics --> 616<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 617<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 618 619<script type="text/javascript"> 620 // chrome doc tracking 621 try { 622 var engdocs = _gat._getTracker("YT-10763712-2"); 623 engdocs._trackPageview(); 624 } catch(err) {} 625 626 // code.google.com site-wide tracking 627 try { 628 _uacct="UA-18071-1"; 629 _uanchor=1; 630 _uff=0; 631 urchinTracker(); 632 } 633 catch(e) {/* urchinTracker not available. */} 634</script> 635<!-- end analytics --> 636 </div> 637 </div> <!-- /gc-footer --> 638 </div> <!-- /gc-container --> 639</body></html> 640
