servicehelper v1.0.5
serviceHelper
A Class with useful methods for PWA applications
Project is currently under development.
How to make my app installable?
The original documentation can be found here: https://web.dev/install-criteria/
1. Add a .webmanifest to your application
Create a file, for example, manifest.webmanifest and save it to your root directory of your app.
Here is a example how it could look like:
{
"short_name": "PWA",
"name": "ProgressiveWebApp",
"description": "My first PWA",
"icons": [
{
"src": "icon.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "big_icon.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": "/?source=pwa",
"display": "standalone",
"theme_color": "blue",
"background_color": "darkblue"
}Some of them are essential. More info in the original documentation.
Now you need to include it to your page with a <link> tag in the <head> tag with the correct path:
<link rel="manifest" href="/manifest.webmanifest">2. Service worker with functional fetch() handler
Add an fetch() handler to your service worker. In my case the name of my service worker is sw.js:
var CACHE_NAME = "someCacheName";
self.addEventListener("fetch", function (event) {
if (event.request.method !== "GET") return;
event.respondWith(
caches.match(event.request).then(function (response) {
// Cache hit - return response
if (response) {
return response;
}
return fetch(event.request).then(function (response) {
// Check if we received a valid response
if (!response || response.status !== 200 || response.type !== "basic") {
return response;
}
// IMPORTANT: Clone the response. A response is a stream
// and because we want the browser to consume the response
// as well as the cache consuming the response, we need
// to clone it so we have two streams.
var responseToCache = response.clone();
caches.open(CACHE_NAME).then(function (cache) {
cache.put(event.request, responseToCache);
});
return response;
});
})
);
});After this, your app is ready to be installable.
How to use serviceHelper?
After you successfully matched the installation criteria, you are ready to use serviceHelper
First: Instantiate the class and pass the path of your service worker.
var sh = new ServiceHelper("./sw.js");Available options now (not stable):
Execute .register() to register your service worker. It returns an promise. It also prevents beforeinstallprompt event and saves this event later for installing the app.
sh.register().then(response => {
console.log("Initialized");
})You can listen on the notinstalled event. It fires only if the app is not installed. Its required first to execute .register().
sh.on("notinstalled", (e) => {
console.log("App is not installed");
//do some stuff. For example enable some button
//button.classList.remove("disabled");
})You can install the app with .installApp(). It returns the saved beforeinstallprompt event. If its already installed, then the promise gets rejected.
You are only able to use this method within a user gesture event:
- change
- click
- contextmenu
- dblclick
- mouseup
- pointerup
- reset
- submit
- touchend
In this example i use the click event:
buttonElement.addEventListener("click", function() {
sh.installApp().then(userResponse => {
console.log("User accepted installation: ", userResponse.accepted);
}).catch(err => {
console.log(err);
})
});Execute .subscribe() to subscribe a user for web push notifications. You need to pass a object with userVisibleOnly and applicationServerKey. The key is expected to be a base 64 string. It gets automaticall converted to Uint8Array:
sh.subscribe(options)
.then(subscription => {
console.log(subscription);
})
.catch(err => {
console.log(err);
})After this, you should be able to receive push notifications.
Some useful methods:
getConfigs()Returns an object with some information.isGranted()Returnstruefor granted otherwisefalseisDenied()Returnstruefor denied otherwisefalsealreadyAsked()Returnstrueif the permission prompt already popped up once
To check if the user is already subscribed run the method isSubscribed(). The promise gets rejected if there is no subscription available:
sh.isSubscribed().then(subscription => {
console.log(subscription);
})
.catch(err => {
console.log(err);
})