ServiceWorkerGlobalScope

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.

* Some parts of this feature may have varying levels of support.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is only available in Service Workers.

The ServiceWorkerGlobalScope interface of the Service Worker API represents the global execution context of a service worker.

Developers should keep in mind that the ServiceWorker state is not persisted across the termination/restart cycle, so each event handler should assume it's being invoked with a bare, default global state.

Once successfully registered, a service worker can and will be terminated when idle to conserve memory and processor power. An active service worker is automatically restarted to respond to events, such as fetch or message.

Additionally, synchronous requests are not allowed from within a service worker — only asynchronous requests, like those initiated via the fetch() method, can be used.

This interface inherits from the WorkerGlobalScope interface, and its parent EventTarget.

Instance properties

This interface inherits properties from the WorkerGlobalScope interface, and its parent EventTarget.

ServiceWorkerGlobalScope.clients Read only: Contains the Clients object associated with the service worker.
ServiceWorkerGlobalScope.cookieStore Read only: Returns a reference to the CookieStore object associated with the service worker.
ServiceWorkerGlobalScope.registration Read only: Contains the ServiceWorkerRegistration object that represents the service worker's registration.
ServiceWorkerGlobalScope.serviceWorker Read only: Contains the ServiceWorker object that represents the service worker.

Instance methods

This interface inherits methods from the WorkerGlobalScope interface, and its parent EventTarget.

ServiceWorkerGlobalScope.skipWaiting(): Allows the current service worker registration to progress from waiting to active state while service worker clients are using it.

Events

Listen to this event using addEventListener() or by assigning an event listener to the oneventname property of this interface.

activate: Occurs when a ServiceWorkerRegistration acquires a new ServiceWorkerRegistration.active worker.
backgroundfetchabort Experimental: Fired when a background fetch operation has been canceled by the user or the app.
backgroundfetchclick Experimental: Fired when the user has clicked on the UI for a background fetch operation.
backgroundfetchfail Experimental: Fired when at least one of the requests in a background fetch operation has failed.
backgroundfetchsuccess Experimental: Fired when all of the requests in a background fetch operation have succeeded.
canmakepayment Experimental: Fired on a payment app's service worker to check whether it is ready to handle a payment. Specifically, it is fired when the merchant website calls the PaymentRequest() constructor.
contentdelete Experimental: Occurs when an item is removed from the ContentIndex.
cookiechange Experimental: Fired when a cookie change has occurred that matches the service worker's cookie change subscription list.
fetch: Occurs when a fetch() is called.
install: Occurs when a ServiceWorkerRegistration acquires a new ServiceWorkerRegistration.installing worker.
message: Occurs when incoming messages are received. Controlled pages can use the MessagePort.postMessage() method to send messages to service workers.
messageerror: Occurs when incoming messages can't be deserialized.
notificationclick: Occurs when a user clicks on a displayed notification.
notificationclose: Occurs when a user closes a displayed notification.
paymentrequest Experimental: Fired on a payment app when a payment flow has been initiated on the merchant website via the PaymentRequest.show() method.
sync: Triggered when a call to SyncManager.register is made from a service worker client page. The attempt to sync is made either immediately if the network is available or as soon as the network becomes available.
periodicsync Experimental: Occurs at periodic intervals, which were specified when registering a PeriodicSyncManager.
push: Occurs when a server push notification is received.
pushsubscriptionchange: Occurs when a push subscription has been invalidated, or is about to be invalidated (e.g. when a push service sets an expiration time).

Examples

This code snippet is from the service worker prefetch sample (see prefetch example live.) The onfetch event handler listens for the fetch event. When fired, the code returns a promise that resolves to the first matching request in the Cache object. If no match is found, the code fetches a response from the network.

The code also handles exceptions thrown from the fetch() operation. Note that an HTTP error response (e.g., 404) will not trigger an exception. It will return a normal response object that has the appropriate error code set.

self.addEventListener("fetch", (event) => {
  console.log("Handling fetch event for", event.request.url);

  event.respondWith(
    caches.match(event.request).then((response) => {
      if (response) {
        console.log("Found response in cache:", response);

        return response;
      }
      console.log("No response found in cache. About to fetch from network…");

      return fetch(event.request).then(
        (response) => {
          console.log("Response from network is:", response);

          return response;
        },
        (error) => {
          console.error("Fetching failed:", error);

          throw error;
        },
      );
    }),
  );
});

Specifications

Specification
Service Workers # serviceworkerglobalscope-interface

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
ServiceWorkerGlobalScope
abortpayment event
ExperimentalNon-standard
activate event
backgroundfetchabort event
Experimental
backgroundfetchclick event
Experimental
backgroundfetchfail event
Experimental
backgroundfetchsuccess event
Experimental
canmakepayment event
Experimental
clients
contentdelete event
Experimental
cookieStore
cookiechange event
Experimental
fetch event
install event
message event
messageerror event
notificationclick event
notificationclose event
paymentrequest event
Experimental
periodicsync event
Experimental
push event
pushsubscriptionchange event
registration
serviceWorker
skipWaiting
sync event

	desktop					mobile
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on iOS	Samsung Internet	WebView Android	WebView on iOS
`ServiceWorkerGlobalScope`
`abortpayment` event ExperimentalNon-standard
`activate` event
`backgroundfetchabort` event Experimental
`backgroundfetchclick` event Experimental
`backgroundfetchfail` event Experimental
`backgroundfetchsuccess` event Experimental
`canmakepayment` event Experimental
`clients`
`contentdelete` event Experimental
`cookieStore`
`cookiechange` event Experimental
`fetch` event
`install` event
`message` event
`messageerror` event
`notificationclick` event
`notificationclose` event
`paymentrequest` event Experimental
`periodicsync` event Experimental
`push` event
`pushsubscriptionchange` event
`registration`
`serviceWorker`
`skipWaiting`
`sync` event