Get unlimited public & private packages + package-based permissions with npm Pro.Get started »

easy-pwa-js

1.0.0-beta.3 • Public • Published

EasyPWA

Tools for managing your Progressive Web App.

Features

  • Manage PWA features easily
  • Manage Push Notifications easily.
  • A specific helper is showed for each browser to help people to install your app.

Example

An example is available here: https://easy-pwa.github.io/easy-pwa-js/

Install

ES6

npm install easy-pwa-js

Use it in your modules:

import EasyPwaManager from 'easy-pwa-js/front';

In your service worker:

importScripts('easy-pwa-js/sw.js');

Standard method

Add this script on your page:

<script type="module" src="https://cdn.jsdelivr.net/npm/easy-pwa-js@1.0/dist/front.js"></script>

Add this script in your service worker:

importScripts('https://cdn.jsdelivr.net/npm/easy-pwa-js@1.0/dist/sw.js');

How to use it

Initialize EasyPWA

For beginning, initialize EasyPWA with your configuration.

EasyPWA.init({
    swPath: '/example/sw.js',
    swRegistrationOptions: {scope: '/'},
    debug: true,
    desktop: true,
});

Invite the user to install your app

If a helper is available for the current browser, an event is automatically emitted by EasyPWA. You have to listen and interact with it.

Automatic method

With this method, a standard invite is showed:

window.addEventListener('easy-pwa-helper-available', function(e) {
    e.detail.showInvite();
});

For a custom invite

If you want to create your own invite for a customized style.

Example of your html invite:

<div id="my_custom_invite">
Install my app ?
<button id="invite_accept">yes</button>
<button id="invite_dismiss">no</button>
</div>

javascript invite:

window.addEventListener('easy-pwa-helper-available', function(e) {
    var helperAvailableEvent = e.detail;
 
    document.getElementById('invite_accept').addEventListener('click', function() {
        document.getElementById('my_custom_invite').display = 'none';
        helperAvailableEvent.acceptInvite();
    });
 
document.getElementById('invite_dismiss').addEventListener('click', function() {
        document.getElementById('my_custom_invite').display = 'none';
        helperAvailableEvent.dismissInvite();
    });
});

Enable push notifications (with Firebase)

Add firebase library and initialize en new app.

var firebaseConfig = {
    apiKey: "...",
    projectId: "...",
    messagingSenderId: "...",
    appId: "..."
};
 
var myFirebaseApp = firebase.initializeApp(firebaseConfig); // firebase initializing

Add in your config, the firebase app instance:

EasyPWA.init({
    ...,
    firebaseApp: myFirebaseApp,
    newTokenFetchedCallback: (token) => {
        // returns a promise
        return fetch('http://.../send-token-to-server.php?token='+token);
    },
}

Always wait EasyPWA is fully initialized before.

window.addEventListener('easy-pwa-ready', function(e) {
    EasyPWA.requestPermission().then( function() {
        // Permissions is now granted
 
        // I don't have a token
        EasyPWA.firebase().getToken().then( function(token) {
           console.log('token', token);
        });
    });
});

Available configuration

A list of configuration elements if available here

Available functions

Initialize EasyPWA

EasyPWA.init({...});

Get manifest data

var manifest = EasyPWA.getManifest();
console.log('The name is: '+manifest.name);

Check if PWA is in standalone mode

if (EasyPWA.isAppMode()) {
    console.log('Site is open as an app');
}

Check if notification is supported on this current browser

if (EasyPWA.isNotificationSupported()) {
    console.log('Notification is supported on this browser.');
}

Request permission to send notification

First, you need to ask permission.

EasyPWA.requestNotificationPermission().then(function() {
    console.log('Accepted. You can get a token with Firebase.');
}).catch(function() {
    console.log('denied. User must authorize notifications in their bowser settings.');
});

Show a local notification

EasyPWA.showNotification('title', {
    icon: ...,
    vibrate: [50, 300, 50]
});

Firebase

Initialize Firebase
var myFirebaseApp = firebase.initializeApp({...});
EasyPWA.init({
    ...
    firebaseApp: myFirebaseApp,
});
Get the token (and send it to the server if new)
EasyPWA.firebase().getToken().then( function(token) {
    console.log('new token: '+token);
});
Delete a token
EasyPWA.firebase().deleteToken(token).then(function(){
    console.log('Token deleted');
});

Available Events

Wait Easy PWA is fully initialized

window.addEventListener('easy-pwa-ready', function(e) {
    console.log('I'm ready!');
});

Listening if install prompt is available

window.addEventListener('easy-pwa-helper-available', function(e) {
    console.log('A helper is available for this browser!');
    var helperAvailableEvent = e.detail;
 
 
    helperAvailableEvent.showInvite();
    // OR
    helperAvailableEvent.acceptInvite();
    helperAvailableEvent.dismissInvite();
});

Detect page is changing

In standalone mode, there are not browser elements visible. So, maybe, you would like to show a loader when page is changing.

window.addEventListener('easy-pwa-page-changing', function(e) {
    console.log('Show a loader, page is changing!');
});

Other tools

Managing online/offline view by css

When you are offline, the css class "offline" is added on the body tag.

<body class="... offline">
    <div class="text-offline">You are offline but you can still access to your favorite website.</div>
</body>
.text-offline {
    display: none;
}
 
.offline .text-offline {
    display: block;
}

Service worker

Plugins

Substitution Page

Show a substitution page when the user is offline

self.EasyPwaSW.pageSubstitutionPlugin().run('easy-pwa-substitution', '/offline.html');

External library included

  • PWACompat is a library that brings the Web App Manifest to non-compliant browsers for better Progressive Web Apps.

Help

Use chrome browser for testing you PWA, there are more available tools:

Install

npm i easy-pwa-js

DownloadsWeekly Downloads

0

Version

1.0.0-beta.3

License

MIT

Unpacked Size

164 kB

Total Files

24

Last publish

Collaborators

  • avatar