Description | Installs a ServiceWorker for the current page. |
Availability | Stable |
Required Script | <script async custom-element="amp-install-serviceworker" src="https://cdn.ampproject.org/v0/amp-install-serviceworker-0.1.js"></script> |
Supported Layouts | nodisplay |
Examples | Annotated code example for amp-install-serviceworker |
Registers the ServiceWorker given by the src
attribute if the AMP document is loaded from the same origin as the given ServiceWorker URL. If the data-iframe-src
is set, loads that URL as an iframe when the AMP document is served from an AMP cache. This allows ServiceWorker installation from the AMP cache, so that the ServiceWorker is installed by the time users visit the origin site.
This ServiceWorker runs whenever the AMP file is served from the origin where you publish the AMP file. The ServiceWorker will not be loaded when the document is loaded from an AMP cache.
See this article for how ServiceWorkers can help with making the AMP experience awesome with ServiceWorkers.
Example
<amp-install-serviceworker
src="https://www.your-domain.com/serviceworker.js"
data-iframe-src="https://www.your-domain.com/install-serviceworker.html"
layout="nodisplay">
</amp-install-serviceworker>
URL of the ServiceWorker to register.
URL of a HTML document that install a ServiceWorker.
Must have the value nodisplay
.
A regular expression that matches URLs to be rewritten to navigate via shell for no-service-worker fallback. See Shell URL rewrite section for more details.
The value must be a valid JavaScript RegExp string, for instance:
amp.html
.*amp
.*\.amp\.html
.*\/amp$
The URL to the shell to use to rewrite URL navigations for no-service-worker fallback. See Shell URL rewrite section for more details.
The value must be an URL on the same origin as the AMP document itself.
When service workers are not available or not yet active, it's possible to configure URL rewrite to direct navigations to the shell. This way, e.g. AMP Runtime can redirect navigation to the "shell" instead of a "leaf" AMP document.
This fallback is only used when the document is opened on the source origin, and NOT on proxy origin.
The URL rewrite is configured using data-no-service-worker-fallback-url-match
and data-no-service-worker-fallback-shell-url
attributes as following:
<amp-install-serviceworker layout="nodisplay"
src="https://www.your-domain.com/serviceworker.js"
data-no-service-worker-fallback-url-match=".*\.amp.html"
data-no-service-worker-fallback-shell-url="https://pub.com/shell">
</amp-install-serviceworker>
Here:
data-no-service-worker-fallback-shell-url
specifies the link for AMP+PWA shell. It's required to be on the source origin as the AMP document.data-no-service-worker-fallback-url-match
is a JavaScript regular expression that describes how to match “in-shell” links vs non-in-shell links.- Both of these attributes must be present to trigger URL rewrite.
URL rewrite works as following:
- The document provides a configuration that explains how to navigate within the shell.
- AMP Runtime tries to install the service worker.
- If service worker is not installed (not installable), as a fallback AMP Runtime will preload the shell page via a hidden iframe.
- AMP Runtime will intercept the “in-shell” navigations (which will often be AMP-to-AMP navigations) and if the service worker is not running, rewrite the navigation URL to proceed to the “shell”-based URL.
- The shell will startup and run the requested navigation via its router. Typically the shell will immediately execute history.replaceState(href).
A URL is rewritten in the form shell-url#href={encodeURIComponent(href)}
. E.g.:
https://pub.com/doc.amp.html
-->
https://pub.com/shell#href=%2Fdoc.amp.html
Besides rewriting URLs, amp-install-serviceworker
also will try to preload the shell. This is done by creating an iframe with #preload
fragment:
<iframe src="https://pub.com/shell#preload" hidden sandbox="allow-scripts allow-same-origin"></iframe>
For the preload to be effective, of course, the shell response must have appropriate HTTP cache headers.
See amp-install-serviceworker rules in the AMP validator specification.