W3cubDocs

/Web APIs

ServiceWorker

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

The ServiceWorker interface of the Service Worker API provides a reference to a service worker. Multiple browsing contexts (e.g. pages, workers, etc.) can be associated with the same service worker, each through a unique ServiceWorker object.

A ServiceWorker object is available in the ServiceWorkerRegistration.active property, and the ServiceWorkerContainer.controller property — this is a service worker that has been activated and is controlling the page (the service worker has been successfully registered, and the controlled page has been reloaded.)

The ServiceWorker interface is dispatched a set of lifecycle events — install and activate — and functional events including fetch. A ServiceWorker object has an associated ServiceWorker.state, related to its lifecycle.

Service workers allow static import of ECMAScript modules, if supported, using import. Dynamic import is disallowed by the specification — calling import() will throw.

Instance properties

The ServiceWorker interface inherits properties from its parent, EventTarget.

ServiceWorker.scriptURL Read only: Returns the ServiceWorker serialized script URL defined as part of ServiceWorkerRegistration. The URL must be on the same origin as the document that registers the ServiceWorker.
ServiceWorker.state Read only: Returns the state of the service worker. It returns one of the following values: parsed, installing, installed, activating, activated, or redundant.

Instance methods

The ServiceWorker interface inherits methods from its parent, EventTarget.

ServiceWorker.postMessage(): Sends a message — consisting of any structured-cloneable JavaScript object — to the service worker. The message is transmitted to the service worker using a message event on its global scope.

Events

statechange: Fired when ServiceWorker.state changes.
error: Fired when an error happens inside the ServiceWorker object.

Examples

This code snippet is from the service worker registration-events sample (live demo). The code listens for any change in the ServiceWorker.state and returns its value.

if ("serviceWorker" in navigator) {
  navigator.serviceWorker
    .register("service-worker.js", {
      scope: "./",
    })
    .then((registration) => {
      let serviceWorker;
      if (registration.installing) {
        serviceWorker = registration.installing;
        document.querySelector("#kind").textContent = "installing";
      } else if (registration.waiting) {
        serviceWorker = registration.waiting;
        document.querySelector("#kind").textContent = "waiting";
      } else if (registration.active) {
        serviceWorker = registration.active;
        document.querySelector("#kind").textContent = "active";
      }
      if (serviceWorker) {
        // logState(serviceWorker.state);
        serviceWorker.addEventListener("statechange", (e) => {
          // logState(e.target.state);
        });
      }
    })
    .catch((error) => {
      // Something went wrong during registration. The service-worker.js file
      // might be unavailable or contain a syntax error.
    });
} else {
  // The current browser doesn't support service workers.
  // Perhaps it is too old or we are not in a Secure Context.
}

Specifications

Specification
Service Workers # serviceworker-interface

Browser compatibility