src/chrome/common/extensions/docs/templates/articles/event_pages.html

   1 <h1>Event Pages</h1>
   2
   3
   4 <p>
   5 A common need for apps and extensions is to have
   6 a single long-running script to manage some task or state.
   7 Event pages to the rescue.
   8 Event pages are loaded only when they are needed.
   9 When the event page is not actively doing something,
  10 it is unloaded, freeing memory and other system resources.
  11 </p>
  12
  13 {{?is_apps}}
  14 <p>
  15 Chrome Apps always use event pages instead of background pages.
  16 It is not possible for a Chrome App to have a persistent background page.
  17 </p>
  18 {{/is_apps}}
  19
  20 <p>
  21 Event pages are available in the stable channel as of Chrome 22, and the
  22 performance advantages are significant, especially on low-power devices. Please
  23 prefer them to persistent background pages whenever possible for new development
  24 and begin <a href="#transition">migrating existing background pages</a> to this
  25 new model.
  26 </p>
  27
  28 <h2 id="manifest">Manifest</h2>
  29
  30 <p>
  31 Register your event page in the
  32 <a href="manifest">extension manifest</a>:
  33 </p>
  34
  35 {{^is_apps}}
  36 <pre data-filename="manifest.json">
  37 {
  38   "name": "My extension",
  39   ...
  40   <b>"background": {
  41     "scripts": ["eventPage.js"],
  42     "persistent": false
  43   }</b>,
  44   ...
  45 }
  46 </pre>
  47
  48 <p>
  49 Notice that without the "persistent" key, you have
  50 a regular background page. Persistence is what differentiates
  51 an event page from a background page.
  52 </p>
  53 {{/is_apps}}
  54 {{?is_apps}}
  55 <pre data-filename="manifest.json">
  56 {
  57   "name": "My app",
  58   ...
  59   "app": {
  60     <b>"background": {
  61       "scripts": ["eventPage.js"]
  62     }</b>
  63   }
  64   ...
  65 }
  66 </pre>
  67 {{/is_apps}}
  68
  69 <h2 id="lifetime">Lifetime</h2>
  70
  71 <p>
  72 The event page is loaded when it is "needed", and unloaded
  73 when it goes idle again. Here are some examples of things
  74 that will cause the event page to load:
  75 </p>
  76 <ul>
  77 <li>The app or extension is first installed or is updated to a new version
  78 (in order to <a href="#registration">register for events</a>).
  79 <li>The event page was listening for an event, and the event is dispatched.
  80 <li>A content script or other extension
  81 <a href="messaging">sends a message.</a>
  82 <li>Another view in the extension (for example, a popup) calls
  83 <code>$(ref:runtime.getBackgroundPage)</code>.
  84 </ul>
  85
  86 <p>
  87 Once it has been loaded, the event page will stay running
  88 as long as it is active (for example, calling an extension
  89 API or issuing a network request). Additionally, the
  90 event page will not unload until all visible views (for example,
  91 popup windows) are closed and all message ports are closed. Note
  92 that opening a view does not cause the event page to load, but
  93 only prevents it from closing once loaded.
  94 </p>
  95
  96 <p>
  97 Make sure your event page closes as soon as the event that
  98 opened it is processed.
  99 You can observe the lifetime of your event page by
 100 opening Chrome's task manager. You can see when your event
 101 page loads and unloads by observing when an entry for your
 102 extension appears in the list of processes.
 103 </p>
 104
 105 <p>
 106 Once the event page has been idle a short time
 107 (a few seconds), the
 108 <code>$(ref:runtime.onSuspend)</code>
 109 event is dispatched. The event page has a few more seconds to handle this
 110 event before it is forcibly unloaded. If during this time an event occurs which
 111 would normally cause the event page to be loaded, the suspend is canceled
 112 and the <code>$(ref:runtime.onSuspendCanceled)</code> event is dispatched.
 113 </p>
 114
 115 <h2 id="registration">Event registration</h2>
 116
 117 <p>
 118 Chrome keeps track of events that an app or extension has added listeners
 119 for. When it dispatches such an event, the event page is
 120 loaded. Conversely, if the app or extension removes all of its listeners for
 121 an event by calling <code>removeListener</code>, Chrome will no longer
 122 load its event page for that event.
 123 </p>
 124
 125 <p>
 126 Because the listeners themselves only exist in the context of the
 127 event page, you must use <code>addListener</code> each time the event
 128 page loads; only doing so at
 129 <code>$(ref:runtime.onInstalled)</code>
 130 by itself is insufficient.
 131 </p>
 132
 133 <p>
 134 For an example of event registration in action, you can view the
 135 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/gmail/">Google Mail
 136 Checker</a> extension.
 137 </p>
 138
 139 {{^is_apps}}
 140 <h2 id="transition">Convert background page to event page</h2>
 141 <p>
 142 Follow this checklist to convert your extension's
 143 (persistent) background page to an event page.
 144
 145 <ol>
 146   <li>Add <code>"persistent": false</code> to your manifest as shown above.
 147
 148   <li>If your extension uses <code>window.setTimeout()</code> or
 149   <code>window.setInterval()</code>, switch to using the
 150   <a href="alarms">alarms API</a> instead. DOM-based timers won't
 151   be honored if the event page shuts down.
 152
 153   <li>Similarly, other asynchronous HTML5 APIs like notifications and
 154   geolocation will not complete if the event page shuts down. Instead,
 155   use equivalent extension APIs, like
 156   <a href="notifications">notifications</a>.
 157
 158   <li>If your extension uses,
 159   <code>$(ref:extension.getBackgroundPage)</a></code>,
 160   switch to
 161   <code>$(ref:runtime.getBackgroundPage)</code>
 162   instead. The newer method is asynchronous so that it can start the event
 163   page if necessary before returning it.
 164 </ol>
 165 </p>
 166 {{/is_apps}}
 167
 168 <h2 id="best-practices">Best practices when using event pages</h2>
 169 <p>
 170 Keep these tips in mind when using event pages to avoid common subtle pitfalls.
 171
 172 <ol>
 173   <li>Register to receive any events your extension is interested in
 174   each time the event page is loaded. The event page will be loaded once
 175   for each new version of your extension. After that it will only be
 176   loaded to deliver events you have registered for. This generally means that
 177   your event listeners should be added at the top level scope of the event
 178   page, otherwise they may not be available when the event page reloads.
 179
 180   <li>If you need to do some initialization when your extension is
 181   installed or upgraded, listen to the
 182   <code>$(ref:runtime.onInstalled)</code>
 183   event. This is a good place to register for
 184   <a href="declarativeWebRequest">declarativeWebRequest</a> rules,
 185   <a href="contextMenus">contextMenu</a> entries, and other such
 186   one-time initialization.
 187
 188   <li>If you need to keep runtime state in memory throughout a browser
 189   session, use the <a href="storage">storage API</a> or
 190   IndexedDB. Since the event page does not stay loaded for long, you
 191   can no longer rely on global variables for runtime state.
 192
 193   {{^is_apps}}
 194   <li>Use <a href="events#filtered">event filters</a> to restrict
 195   your event notifications to the cases you care about. For example, if
 196   you listen to the <code><a href="extensions/tabs#event-onUpdated">tabs.onUpdated</a></code>
 197   event, try using the
 198   <code>$(ref:webNavigation.onCompleted)</code>
 199   event with filters instead (the tabs API does not support filters).
 200   That way, your event page will only be loaded for events that
 201   interest you.
 202   {{/is_apps}}
 203
 204   <li>Listen to the
 205   <code>$(ref:runtime.onSuspend)</code>
 206   event if you need to do last second cleanup before your event page
 207   is shut down. However, we recommend persisting periodically instead.
 208   That way if your extension crashes without receiving
 209   <code>onSuspend</code>, no data will typically be lost.
 210
 211   <li>If you're using <a href="messaging">message passing</a>, be sure
 212   to close unused message ports. The event page will not shut down until all
 213   message ports are closed.
 214
 215   <li>If you're using the <a href="contextMenus">context menus</a> API,
 216   pass a string <code>id</code> parameter to
 217   <code>$(ref:contextMenus.create)</code>,
 218   and use the
 219   <code>$(ref:contextMenus.onClicked)</code>
 220   callback instead of an <code>onclick</code> parameter to
 221   <code>$(ref:contextMenus.create)</code>.
 222
 223   <li>Remember to test that your event page works properly when it is unloaded
 224   and then reloaded, which only happens after several seconds of inactivity.
 225   Common mistakes include doing unnecessary work at page load time (when it
 226   should only be done when the extension is installed); setting an alarm at
 227   page load time (which resets any previous alarm); or not adding event
 228   listeners at page load time.
 229 </ol>
 230 </p>