1<div id="pageData-name" class="pageData">Desktop Notifications</div>
2<div id="pageData-showTOC" class="pageData">true</div>
3
4<!-- BEGIN AUTHORED CONTENT -->
5<p>
6Use desktop notifications to notify users that something
7important has happened.
8Notifications appear outside the browser window.
9As the following snapshots show,
10the details of how notifications look
11and where they're shown depend on the platform.
12</p>
13
14<img src="images/notification-windows.png"
15  width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
16  alt="Notifications on Microsoft Windows"/>
17<img src="images/notification-mac.png"
18  width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
19  alt="Notifications on Mac OS X"/>
20<img src="images/notification-linux.png"
21  width="28%" style="margin:2em 0.5em 1em; border:1px solid black;"
22  alt="Notifications on Ubuntu Linux"/>
23
24<p>
25You create the notification window
26using a bit of JavaScript and, optionally,
27an HTML page packaged inside your extension.
28</p>
29
30
31<h2 id="manifest">Manifest</h2>
32
33<p>
34You can request the notification permission
35in the <a href="manifest.html">extension manifest</a>,
36like this:
37</p>
38
39<pre>{
40  "name": "My extension",
41  ...
42<b>  "permissions": [
43    "notifications"
44  ]</b>,
45  ...
46}</pre>
47
48<p class="note">
49<b>Note:</b> Extensions that declare
50the <code>notifications</code> permission
51are always allowed to create notifications.
52There is no need to call
53<code>webkitNotifications.checkPermission()</code>.
54</p>
55
56<h2 id="communication">Communicating with other views</h2>
57
58<p>
59You can communicate between a notification
60and other views in your extension using
61<a href="extension.html#method-getBackgroundPage">getBackgroundPage()</a> and
62<a href="extension.html#method-getViews">getViews()</a>. For example:
63</p>
64
65<pre>
66// Inside a notification...
67chrome.extension.getBackgroundPage().doThing();
68
69// From the background page...
70chrome.extension.getViews({type:"notification"}).forEach(function(win) {
71  win.doOtherThing();
72});
73</pre>
74
75
76<h2 id="examples"> Examples </h2>
77
78<p>
79You can find a simple example
80of using notifications in the
81<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/notifications/">examples/api/notifications</a>
82directory.
83For other examples
84and for help in viewing the source code,
85see <a href="samples.html">Samples</a>.
86</p>
87
88<p>
89Also see html5rocks.com's
90<a href="http://www.html5rocks.com/tutorials/notifications/quick/">notifications tutorial</a>.
91Ignore the permission-related code;
92it's unnecessary if you declare the "notifications" permission.
93</p>
94
95<h2 id="api">API</h2>
96
97<p>
98The desktop notification API for extensions
99is the same one that
100is available to normal web pages.
101As the following code shows,
102you first create either a simple text notification
103or an HTML notification,
104and then you show the notification.
105</p>
106
107<pre>
108// Create a simple text notification:
109var notification = webkitNotifications.createNotification(
110  '48.png',  // icon url - can be relative
111  'Hello!',  // notification title
112  'Lorem ipsum...'  // notification body text
113);
114
115// Or create an HTML notification:
116var notification = webkitNotifications.createHTMLNotification(
117  'notification.html'  // html url - can be relative
118);
119
120// Then show the notification.
121notification.show();
122</pre>
123
124<p>For complete API details,
125see the <a href="http://dev.chromium.org/developers/design-documents/desktop-notifications/api-specification">Desktop notifications draft specification</a>.</p>
126
127<!-- END AUTHORED CONTENT -->
128