MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

ServiceWorkerContainer.register()

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 register() method of the ServiceWorkerContainer interface creates or updates a ServiceWorkerRegistration for the given scriptURL.

If successful, a service worker registration ties the provided script URL to a scope, which is subsequently used for navigation matching. You can call this method unconditionally from the controlled page, i.e., you don't need to first check whether there's an active registration.

There is frequent confusion surrounding the meaning and use of scope. Since a service worker can't have a scope broader than its own location, only use the scope option when you need a scope that is narrorwer than the default.

Syntax

ServiceWorkerContainer.register(scriptURL, options)
  .then(function(ServiceWorkerRegistration) { ... });

Parameters

scriptURL
The URL of the service worker script.
options Optional
An options object to provide options upon registration. Currently available options are:
  • scope: A USVString representing a URL that defines a service worker's registration scope; what range of URLs a service worker can control. This is usually a relative URL. The default value is the URL you'd get if you resolved './' using the web page's location as the base. It is not, as is commonly believed, relative to the service worker's location. See the Examples section for more information on how it does work.

Return value

A Promise that resolves with a ServiceWorkerRegistration object.

Examples

The examples described here should be taken together to get a better understanding of how service workers scope applies to a page.

The following example uses the default value of scope (by excluding it). The service worker in this case will control example.com/index.html  as well as something like example.com/product/description.html.

if ('serviceWorker' in navigator) {
  // Register a service worker hosted at the root of the
  // site using the default scope.
  navigator.serviceWorker.register('/sw.js').then(function(registration) {
    console.log('Service worker registration succeeded:', registration);
  }).catch(function(error) {
    console.log('Service worker registration failed:', error);
  });
} else {
  console.log('Service workers are not supported.');
}

The following code if included in a page at the root of a site would apply to exactly the same pages as the example above. Remember the scope, when included, uses the page's location as the base. Alternatively, if this code were included in a page called example.com/product/description.html, the scope of './' would mean that the service worker only applies to resources under example.com/product. If I needed to register a service worker on example.com/product/description.html that applied to all of example.com, I would simply exclude the scope (as is done above).

if ('serviceWorker' in navigator) {
  // Register a service worker hosted at the root of the
  // site using a more restrictive scope.
  navigator.serviceWorker.register('/sw.js', {scope: './'}).then(function(registration) {
    console.log('Service worker registration succeeded:', registration);
  }).catch(function(error) {
    console.log('Service worker registration failed:', error);
  });
} else {
  console.log('Service workers are not supported.');
}

Specifications

Specification Status Comment
Service Workers
The definition of 'ServiceWorkerContainer' in that specification.
Editor's Draft Initial definition.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 40 44.0 (44.0)[1] No support 24 No support
Feature Android Webview Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support No support 40 44.0 (44.0) (Yes) No support ? No support

[1] Service workers (and Push) have been disabled in the Firefox 45 and 52 Extended Support Releases (ESR.)

Document Tags and Contributors

 Last updated by: jeffposnick,