@angular/service-worker
- Version 18.2.2
- Published
- 316 kB
- 1 dependency
- MIT license
Install
npm i @angular/service-worker
yarn add @angular/service-worker
pnpm add @angular/service-worker
Overview
Angular - service worker tooling!
Index
Functions
Classes
Interfaces
Type Aliases
Functions
function provideServiceWorker
provideServiceWorker: ( script: string, options?: SwRegistrationOptions) => EnvironmentProviders;
Sets up providers to register the given Angular Service Worker script.
If
enabled
is set tofalse
in the given options, the module will behave as if service workers are not supported by the browser, and the service worker will not be registered.Example usage:
bootstrapApplication(AppComponent, {providers: [provideServiceWorker('ngsw-worker.js')],});
Classes
class ServiceWorkerModule
class ServiceWorkerModule {}
property ɵfac
static ɵfac: i0.ɵɵFactoryDeclaration<ServiceWorkerModule, never>;
property ɵinj
static ɵinj: i0.ɵɵInjectorDeclaration<ServiceWorkerModule>;
property ɵmod
static ɵmod: i0.ɵɵNgModuleDeclaration<ServiceWorkerModule, never, never, never>;
method register
static register: ( script: string, options?: SwRegistrationOptions) => ModuleWithProviders<ServiceWorkerModule>;
Register the given Angular Service Worker script.
If
enabled
is set tofalse
in the given options, the module will behave as if service workers are not supported by the browser, and the service worker will not be registered.
class SwPush
class SwPush {}
Subscribe and listen to [Web Push Notifications](https://developer.mozilla.org/en-US/docs/Web/API/Push_API/Best_Practices) through Angular Service Worker.
You can inject a
SwPush
instance into any component or service as a dependency.To subscribe, call
SwPush.requestSubscription()
, which asks the user for permission. The call returns aPromise
with a new [PushSubscription
](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription) instance.A request is rejected if the user denies permission, or if the browser blocks or does not support the Push API or ServiceWorkers. Check
SwPush.isEnabled
to confirm status.Invoke Push Notifications by pushing a message with the following payload.
{"notification": {"actions": NotificationAction[],"badge": USVString,"body": DOMString,"data": any,"dir": "auto"|"ltr"|"rtl","icon": USVString,"image": USVString,"lang": DOMString,"renotify": boolean,"requireInteraction": boolean,"silent": boolean,"tag": DOMString,"timestamp": DOMTimeStamp,"title": DOMString,"vibrate": number[]}}Only
title
is required. SeeNotification
[instance properties](https://developer.mozilla.org/en-US/docs/Web/API/Notification#Instance_properties).While the subscription is active, Service Worker listens for [PushEvent](https://developer.mozilla.org/en-US/docs/Web/API/PushEvent) occurrences and creates [Notification](https://developer.mozilla.org/en-US/docs/Web/API/Notification) instances in response.
Unsubscribe using
SwPush.unsubscribe()
.An application can subscribe to
SwPush.notificationClicks
observable to be notified when a user clicks on a notification. For example:You can read more on handling notification clicks in the [Service worker notifications guide](ecosystem/service-workers/push-notifications).
See Also
[Push Notifications](https://developers.google.com/web/fundamentals/codelabs/push-notifications/)
[Angular Push Notifications](https://blog.angular-university.io/angular-push-notifications/)
[MDN: Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
[MDN: Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
[MDN: Web Push API Notifications best practices](https://developer.mozilla.org/en-US/docs/Web/API/Push_API/Best_Practices)
constructor
constructor(sw: NgswCommChannel);
property isEnabled
readonly isEnabled: boolean;
True if the Service Worker is enabled (supported by the browser and enabled via
ServiceWorkerModule
).
property messages
readonly messages: Observable<object>;
Emits the payloads of the received push notification messages.
property notificationClicks
readonly notificationClicks: Observable<{ action: string; notification: NotificationOptions & { title: string };}>;
Emits the payloads of the received push notification messages as well as the action the user interacted with. If no action was used the
action
property contains an empty string''
.Note that the
notification
property does **not** contain a [Notification][Mozilla Notification] object but rather a [NotificationOptions](https://notifications.spec.whatwg.org/#dictdef-notificationoptions) object that also includes thetitle
of the [Notification][Mozilla Notification] object.[Mozilla Notification]: https://developer.mozilla.org/en-US/docs/Web/API/Notification
property ɵfac
static ɵfac: i0.ɵɵFactoryDeclaration<SwPush, never>;
property ɵprov
static ɵprov: i0.ɵɵInjectableDeclaration<SwPush>;
property subscription
readonly subscription: Observable<PushSubscription>;
Emits the currently active [PushSubscription](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription) associated to the Service Worker registration or
null
if there is no subscription.
method requestSubscription
requestSubscription: (options: { serverPublicKey: string;}) => Promise<PushSubscription>;
Subscribes to Web Push Notifications, after requesting and receiving user permission.
Parameter options
An object containing the
serverPublicKey
string.Returns
A Promise that resolves to the new subscription object.
method unsubscribe
unsubscribe: () => Promise<void>;
Unsubscribes from Service Worker push notifications.
Returns
A Promise that is resolved when the operation succeeds, or is rejected if there is no active subscription or the unsubscribe operation fails.
class SwRegistrationOptions
abstract class SwRegistrationOptions {}
Token that can be used to provide options for
ServiceWorkerModule
outside ofServiceWorkerModule.register()
.You can use this token to define a provider that generates the registration options at runtime, for example via a function call:
property enabled
enabled?: boolean;
Whether the ServiceWorker will be registered and the related services (such as
SwPush
andSwUpdate
) will attempt to communicate and interact with it.Default: true
property registrationStrategy
registrationStrategy?: string | (() => Observable<unknown>);
Defines the ServiceWorker registration strategy, which determines when it will be registered with the browser.
The default behavior of registering once the application stabilizes (i.e. as soon as there are no pending micro- and macro-tasks) is designed to register the ServiceWorker as soon as possible but without affecting the application's first time load.
Still, there might be cases where you want more control over when the ServiceWorker is registered (for example, there might be a long-running timeout or polling interval, preventing the app from stabilizing). The available option are:
-
registerWhenStable:<timeout>
: Register as soon as the application stabilizes (no pending micro-/macro-tasks) but no later than<timeout>
milliseconds. If the app hasn't stabilized after<timeout>
milliseconds (for example, due to a recurrent asynchronous task), the ServiceWorker will be registered anyway. If<timeout>
is omitted, the ServiceWorker will only be registered once the app stabilizes. -registerImmediately
: Register immediately. -registerWithDelay:<timeout>
: Register with a delay of<timeout>
milliseconds. For example, useregisterWithDelay:5000
to register the ServiceWorker after 5 seconds. If<timeout>
is omitted, is defaults to0
, which will register the ServiceWorker as soon as possible but still asynchronously, once all pending micro-tasks are completed. - An Observable factory function: A function that returns anObservable
. The function will be used at runtime to obtain and subscribe to theObservable
and the ServiceWorker will be registered as soon as the first value is emitted.Default: 'registerWhenStable:30000'
property scope
scope?: string;
A URL that defines the ServiceWorker's registration scope; that is, what range of URLs it can control. It will be used when calling [ServiceWorkerContainer#register()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register).
class SwUpdate
class SwUpdate {}
Subscribe to update notifications from the Service Worker, trigger update checks, and forcibly activate updates.
See Also
constructor
constructor(sw: NgswCommChannel);
property isEnabled
readonly isEnabled: boolean;
True if the Service Worker is enabled (supported by the browser and enabled via
ServiceWorkerModule
).
property ɵfac
static ɵfac: i0.ɵɵFactoryDeclaration<SwUpdate, never>;
property ɵprov
static ɵprov: i0.ɵɵInjectableDeclaration<SwUpdate>;
property unrecoverable
readonly unrecoverable: Observable<UnrecoverableStateEvent>;
Emits an
UnrecoverableStateEvent
event whenever the version of the app used by the service worker to serve this client is in a broken state that cannot be recovered from without a full page reload.
property versionUpdates
readonly versionUpdates: Observable<VersionEvent>;
Emits a
VersionDetectedEvent
event whenever a new version is detected on the server.Emits a
VersionInstallationFailedEvent
event whenever checking for or downloading a new version fails.Emits a
VersionReadyEvent
event whenever a new version has been downloaded and is ready for activation.
method activateUpdate
activateUpdate: () => Promise<boolean>;
Updates the current client (i.e. browser tab) to the latest version that is ready for activation.
In most cases, you should not use this method and instead should update a client by reloading the page.
Updating a client without reloading can easily result in a broken application due to a version mismatch between the application shell and other page resources, such as lazy-loaded chunks, whose filenames may change between versions.
Only use this method, if you are certain it is safe for your specific use case.
Returns
a promise that - resolves to
true
if an update was activated successfully - resolves tofalse
if no update was available (for example, the client was already on the latest version). - rejects if any error occurs
method checkForUpdate
checkForUpdate: () => Promise<boolean>;
Checks for an update and waits until the new version is downloaded from the server and ready for activation.
Returns
a promise that - resolves to
true
if a new version was found and is ready to be activated. - resolves tofalse
if no new version was found - rejects if any error occurs
Interfaces
interface NoNewVersionDetectedEvent
interface NoNewVersionDetectedEvent {}
An event emitted when the service worker has checked the version of the app on the server and it didn't find a new version that it doesn't have already downloaded.
See Also
interface UnrecoverableStateEvent
interface UnrecoverableStateEvent {}
An event emitted when the version of the app used by the service worker to serve this client is in a broken state that cannot be recovered from and a full page reload is required.
For example, the service worker may not be able to retrieve a required resource, neither from the cache nor from the server. This could happen if a new version is deployed to the server and the service worker cache has been partially cleaned by the browser, removing some files of a previous app version but not all.
See Also
interface VersionDetectedEvent
interface VersionDetectedEvent {}
An event emitted when the service worker has detected a new version of the app on the server and is about to start downloading it.
See Also
interface VersionInstallationFailedEvent
interface VersionInstallationFailedEvent {}
An event emitted when the installation of a new version failed. It may be used for logging/monitoring purposes.
See Also
interface VersionReadyEvent
interface VersionReadyEvent {}
An event emitted when a new version of the app is available.
See Also
property currentVersion
currentVersion: { hash: string; appData?: object;};
property latestVersion
latestVersion: { hash: string; appData?: object;};
property type
type: 'VERSION_READY';
Type Aliases
type VersionEvent
type VersionEvent = | VersionDetectedEvent | VersionInstallationFailedEvent | VersionReadyEvent | NoNewVersionDetectedEvent;
A union of all event types that can be emitted by SwUpdate#versionUpdates.
Package Files (1)
Dependencies (1)
Dev Dependencies (0)
No dev dependencies.
Peer Dependencies (2)
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@angular/service-worker
.
- Markdown[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@angular/service-worker)
- HTML<a href="https://www.jsdocs.io/package/@angular/service-worker"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 3763 ms. - Missing or incorrect documentation? Open an issue for this package.