ServiceWorkerGlobalScope
This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
The ServiceWorkerGlobalScope
interface of the ServiceWorker 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 ServiceWorkerGlobalScope.onfetch
or ServiceWorkerGlobalScope.onmessage
.
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
, and therefore implements properties from WindowTimers
, WindowBase64
, and WindowEventHandlers
.
<div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 12.142857142857142%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-20 0 700 85" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25 121,20 121,30 111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope" target="_top"><rect x="151" y="1" width="170" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="236" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">WorkerGlobalScope</text></a><polyline points="321,25 331,20 331,30 321,25" stroke="#D4DDE4" fill="none"/><line x1="331" y1="25" x2="361" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope" target="_top"><rect x="361" y="1" width="240" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text x="481" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">ServiceWorkerGlobalScope</text></a></svg></div>
a:hover text { fill: #0095DD; pointer-events: all;}
Properties
ServiceWorkerGlobalScope.clients
Read only- Contains the
Clients
object associated with the service worker. ServiceWorkerGlobalScope.registration
Read only- Contains the
ServiceWorkerRegistration
object that represents the service worker's registration. ServiceWorkerGlobalScope.caches
Read only- Contains the
CacheStorage
object associated with the service worker.
Event handlers
ServiceWorkerGlobalScope.onactivate
- An event handler fired whenever an
activate
event occurs — when aServiceWorkerRegistration
acquires a newServiceWorkerRegistration.active
worker. ServiceWorkerGlobalScope.onfetch
- An event handler fired whenever a
fetch
event occurs — when afetch()
is called. ServiceWorkerGlobalScope.oninstall
- An event handler fired whenever an
install
event occurs — when aServiceWorkerRegistration
acquires a newServiceWorkerRegistration.installing
worker. ServiceWorkerGlobalScope.onmessage
- An event handler fired whenever a
message
event occurs — when incoming messages are received. Controlled pages can use theMessagePort.postMessage()
method to send messages to service workers. The service worker can optionally send a response back via theMessagePort
exposed inevent.data.port
, corresponding to the controlled page. ServiceWorkerGlobalScope.onnotificationclick
- An event handler fired whenever a
notificationclick
event occurs — when a user clicks on a displayed notification. ServiceWorkerGlobalScope.onnotificationclose
- An event handler fired whenever a
notificationclose
event occurs — when a user closes a displayed notification. ServiceWorkerGlobalScope.onpush
- An event handler fired whenever a
push
event occurs — when a server push notification is received. ServiceWorkerGlobalScope.onpushsubscriptionchange
- An event handler fired whenever a
pushsubscriptionchange
event occurs — when a push subscription has been invalidated, or is about to be invalidated (e.g. when a push service sets an expiration time.) ServiceWorkerGlobalScope.onsync
- An event handler fired whenever a
SyncEvent
event occurs. This is triggered when a call toSyncManager.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.
Methods
ServiceWorkerGlobalScope.skipWaiting()
- Allows the current service worker registration to progress from waiting to active state while service worker clients are using it.
ServiceWorkerGlobalScope
implements WorkerGlobalScope
— which implements GlobalFetch
. Therefore it also has the following property available to it:
GlobalFetch.fetch()
- Starts the process of fetching a resource. This returns a promise that resolves to the
Response
object representing the response to your request. This algorithm is the entry point for the fetch handling handed to the service worker context.
Examples
This code snippet is from the service worker prefetch sample (see prefetch example live.) The ServiceWorkerGlobalScope.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', function(event) { console.log('Handling fetch event for', event.request.url); event.respondWith( caches.match(event.request).then(function(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(function(response) { console.log('Response from network is:', response); return response; }).catch(function(error) { console.error('Fetching failed:', error); throw error; }); }) ); });
Specifications
Specification | Status | Comment |
---|---|---|
Service Workers The definition of 'ServiceWorkerGlobalScope' in that specification. |
Working Draft | Initial definition |
Fetch The definition of 'Fetch' in that specification. |
Living Standard | Adds the fetch method. |
Push API The definition of 'onpush' in that specification. |
Working Draft | Adds the onpush and onpushsubscriptionchange event handlers. |
Notifications API The definition of 'onnotificationclick' in that specification. |
Recommendation | Adds the onnotificationclick event handler. |
Web Background Synchronization The definition of 'onsync' in that specification. |
Living Standard | Adds the onsync event. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 40.0 | 44.0 (44.0)[1] | No support | 24 | No support |
onnotificationclick |
(Yes) | 42.0 (42.0)[1] | No support | (Yes) | No support |
onsync |
49.0 | ? | ? | ? | ? |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic support | No support | No support | 44.0 (44.0) | (Yes) | No support | ? | No support | 40.0 |
onnotificationclick |
No support | No support | 42.0 (42.0) | (Yes) | No support | ? | No support | (Yes) |
onsync |
No support | No support | ? | ? | ? | ? | ? | 49.0 |
[1] Service workers (and Push) have been disabled in the Firefox 45 Extended Support Release (ESR.)
See also
- Using Service Workers
- Service workers basic code example
- Is ServiceWorker ready?
Promise
- Using web workers
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/serviceworkerglobalscope