Extension service workers support both
standard service worker
events and many events in the
extension APIs
. This section describes what's available and provides tips for using them.
Declare extension events
Event handlers in service workers need to be declared in the global scope, meaning they should be at the top level of the script and not be nested inside functions. This ensures that they are registered synchronously on initial script execution, which enables Chrome to dispatch events to the service worker as soon as it starts. For example:
Not advised
chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
chrome.action.setBadgeText({ text: badgeText });
chrome.action.onClicked.addListener(handleActionClick);
});
Better
chrome.action.onClicked.addListener(handleActionClick);
chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
chrome.action.setBadgeText({ text: badgeText });
});
Common events
Extension service workers support events in specific APIs. A few common ones are described in what follows. Note that some of these APIs require permissions to use and others may have events, methods, or properties that are not available in all versions of Chrome. For details, see the linked API documentation, particularly the events, methods, or properties you want to use.
chrome.action
- Fired in response to a user interaction with your extension's toolbar icon, whether that action be for a specific page (tab) or for the whole extension.
chrome.management
- Provides events related to the installation, uninstallation, enabling, and disabling extensions.
chrome.notifications
- Provides events related to the user's interaction with system notifications generated by the extension.
chrome.permissions
- Indicates when extension permissions are granted or revoked by the user.
chrome.runtime
- Provides events related to the extension lifecycle, messages sent from other parts of the extension, and notification of an available extension or Chrome update.
chrome.storage.onChanged
- Fired whenever any
StorageArea
object is cleared or when the value of a key is changed or set. Note that the each
StorageArea
instance has its own
onChanged
event.
chrome.webNavigation
- Provides information about the status of in-flight navigation requests.
Filters
To restrict events to specific use case, or eliminate unnecessary event calls, use APIs that support
event filters
. For example, consider an extension listening for the
tabs.onUpdated
event to detect when a user navigates to a specific website. This event will be called on every navigation on every tab. Instead, use
webNavigation.onCompleted
with a filter. For example:
const filter = {
url: [
{
urlMatches: 'https://www.google.com/',
},
],
};
chrome.webNavigation.onCompleted.addListener(() => {
console.info("The user has loaded my favorite website!");
}, filter);
Web service worker events
Extension service workers support more than the lifecycle events
described elsewhere
.
ServiceWorkerGlobal.fetch
Fired when anything is retrieved from the extension package or when
fetch()
and
XMLHttpRequest()
are called from an extension or popup script. (Calls from content scripts are not intercepted by the service worker
fetch
handler.) In the latter cases, you will need to add the URLs of the pages you want to fetch to the
"host_permissions"
key in the
manifest.json
.
ServiceWorkerGlobal.message
Service worker message passing is available in addition to extension
messaging passing
, but the two systems are not interoperable. That means that messages sent using
sendMessage()
(which is available from several extension APIs) aren't intercepted by service worker message handlers. Likewise, messages sent using
postMessage()
aren't intercepted by extension message handlers. Both types of message handlers?meaning both
ServiceWorkerGlobal.message
and
chrome.runtime.onMessage
?are supported in extension service workers.
You should prefer
extension messaging
unless you have a specific reason for using service worker messaging.