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

<h1>Event Pages</h1>


<p>
Event pages are very similar to
<a href="background_pages.html">background pages</a>,
with one important difference:
event pages are loaded only when they are needed.
When the event page is not actively doing something,
it is unloaded, freeing memory and other system resources.
</p>

<h2 id="manifest">Manifest</h2>

<p>
Register your event page in the
<a href="manifest.html">extension manifest</a>:
</p>

<pre>{
  "name": "My extension",
  ...
  <b>"background": {
    "scripts": ["eventPage.js"],
    "persistent": false
  }</b>,
  ...
}</pre>

<p>
Notice that without the "persistent" key, you have
a regular background page. Persistence is what differentiates
an event page from a background page.
</p>

<h2 id="lifetime">Lifetime</h2>

<p>
The event page is loaded when it is "needed", and unloaded
when it goes idle again. Here are some examples of things
that will cause the event page to load:
</p>
<ul>
<li>The extension is first installed or is updated to a new version
(in order to <a href="#registration">register for events</a>).
<li>The event page was listening for an event, and the event is dispatched.
<li>A content script or other extension
<a href="messaging.html">sends a message.</a>
<li>Another view in the extension (for example, a popup) calls
<code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgroundPage()</a></code>.
</ul>

<p>
Once it has been loaded, the event page will stay running
as long as it is active (for example, calling an extension
API or issuing a network request). Additionally, the
event page will not unload until all visible views (for example,
popup windows) are closed and all message ports are closed.
</p>

<p>
You can observe the lifetime of your event page by clicking
on "View Background Pages" in Chrome's Wrench menu, or by
opening Chrome's task manager. You can see when your event
page loads and unloads by observing when an entry for your
extension appears in the list of processes.
</p>

<p>
Once the event page has been idle a short time
(a few seconds), the
<code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code>
event is dispatched. The event page has a few more seconds to handle this
event before it is forcibly unloaded. Note that once the event is dispatched,
new activity will not keep the event page open.
</p>

<h2 id="registration">Event registration</h2>

<p>
Chrome keeps track of events that an extension has added listeners
for. When it dispatches such an event, the extension's event page is
loaded. Conversely, if the extension removes all of its listeners for
an event by calling <code>removeListener</code>, Chrome will no longer
load its event page for that event.
</p>

<p>
Because the listeners themselves only exist in the context of the
event page, you must use <code>addListener</code> each time the event
page loads; only doing so at
<code><a href="runtime.html#event-onInstalled">chrome.runtime.onInstalled</a></code>
by itself is insufficient.
</p>

<p>
For an example of event registration in action, you can view the
<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/gmail/">Google Mail
Checker</a> extension.
</p>

<h2 id="transition">Convert background page to event page</h2>
<p>
Follow this checklist to convert your extension's
(persistent) background page to an event page.

<ol>
  <li>Add <code>"persistent": false</code> to your manifest as shown above.

  <li>Register to receive any events your extension is interested in
  each time the event page is loaded. The event page will be loaded once
  for each new version of your extension. After that it will only be
  loaded to deliver events you have registered for.

  <li>If you need to do some initialization when your extension is
  installed or upgraded, listen to the
  <code><a href="runtime.html#event-onInstalled">chrome.runtime.onInstalled</a></code>
  event. If you need to do some initialization each time the browser starts,
  listen to the
  <code><a href="runtime.html#event-onBrowserStartup">chrome.runtime.onBrowserStartup</a></code>
  event; however, you should (in almost all cases) prefer
  the <code>chrome.runtime.onInstalled</code> event.

  <li>If you need to keep runtime state in memory throughout a browser
  session, use the <a href="storage.html">storage API</a> or
  IndexedDB. Since the event page does not stay loaded for long, you
  can no longer rely on global variables for runtime state.

  <li>Use <a href="events.html#filtered">event filters</a> to restrict
  your event notifications to the cases you care about. For example, if
  you listen to the <code><a href="tabs.html#event-onUpdated">tabs.onUpdated</a></code>
  event, try using the
  <code><a href="webNavigation.html#event-onCompleted">webNavigation.onComplete</a></code>
  event with filters instead (the tabs API does not support filters).
  That way, your event page will only be loaded for events that
  interest you.

  <li>Listen to the
  <code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code>
  event if you need to do last second cleanup before your event page
  is shut down. However, we recommend persisting periodically instead.
  That way if your extension crashes without receiving
  <code>onSuspend</code>, no data will typically be lost.

  <li>If your extension uses <code>window.setTimeout()</code> or
  <code>window.setInterval()</code>, switch to using the
  <a href="alarms.html">alarms API</a> instead. DOM-based timers won't
  be honored if the event page shuts down.

  <li>If your extension uses,
  <code><a href="extension.html#method-getBackgroundPage">chrome.extension.getBackgroundPage()</a></code>,
  switch to
  <code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgroundPage()</a></code>
  instead. The newer method is asynchronous so that it can start the event
  page if necessary before returning it.

  <li>If you're using <a href="messaging.html">message passing</a>, be sure
  to close unused message ports. The event page will not shut down until all
  message ports are closed.
</ol>
</p>