Google Chrome Extensions

Event Pages

Event pages are very similar to background pages, 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.

Manifest

Register your event page in the extension manifest: 

{
  "name": "My extension",
  ...
  "background": {
    "scripts": ["eventPage.js"],
    "persistent": false
  },
  ...
}

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

Lifetime

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:

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.

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.

Once the event page has been idle a short time (a few seconds), the chrome.runtime.onSuspend 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.

Event registration

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 removeListener, Chrome will no longer load its event page for that event.

Because the listeners themselves only exist in the context of the event page, you must use addListener each time the event page loads; only doing so at chrome.runtime.onInstalled by itself is insufficient.

For an example of event registration in action, you can view the Google Mail Checker extension.

Convert background page to event page

Follow this checklist to convert your extension's (persistent) background page to an event page.

  1. Add "persistent": false to your manifest as shown above.
  2. 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.
  3. If you need to do some initialization when your extension is installed or upgraded, listen to the chrome.runtime.onInstalled event. If you need to do some initialization each time the browser starts, listen to the chrome.runtime.onBrowserStartup event; however, you should (in almost all cases) prefer the chrome.runtime.onInstalled event.
  4. If you need to keep runtime state in memory throughout a browser session, use the storage API or IndexedDB. Since the event page does not stay loaded for long, you can no longer rely on global variables for runtime state.
  5. Use event filters to restrict your event notifications to the cases you care about. For example, if you listen to the tabs.onUpdated event, try using the webNavigation.onComplete 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.
  6. Listen to the chrome.runtime.onSuspend 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 onSuspend, no data will typically be lost.
  7. If your extension uses window.setTimeout() or window.setInterval(), switch to using the alarms API instead. DOM-based timers won't be honored if the event page shuts down.
  8. If your extension uses, chrome.extension.getBackgroundPage(), switch to chrome.runtime.getBackgroundPage() instead. The newer method is asynchronous so that it can start the event page if necessary before returning it.
  9. If you're using message passing, be sure to close unused message ports. The event page will not shut down until all message ports are closed.