PWA

The skeleton is a Progressive Web App (PWA), which means it functions as both a web page and a mobile app, offering a versatile experience on any device.

TIP

To build and run the skeleton as a PWA, check out the main commands here

Configuration

Web app manifest

A web app manifest provides essential information about the application, such as its name, author, icon, and description, in a JSON text document. The purpose of the manifest is to allow the installation of applications on a device's home screen. You can find this manifest in the Quasar configuration.

Service Worker

Service workers, which operate as JavaScript events, are a core component of a PWA and act as a proxy. They enable fast loading, offline access, push notifications, and other capabilities.

TIP

When the application is ready to be installed or updated, a pop-up window will appear.

Implementing web push notifications

This section outlines the process for integrating web push notifications into a Kalisio application. Web push notifications allow your application to send real-time notifications to users' devices.

TIP

Web push notifications are managed by the feathers-webpush module, which must be added as a dependency in the application's development folder.

Step 1: Generate VAPID keys

VAPID (Voluntary Application Server Identification) keys are required for securely sending push notifications. These keys identify your application to the push service and are used for encrypting payloads.

1. Install the web-push library globally to use its command-line interface (CLI):

npm install web-push -g

2. Generate VAPID Keys

web-push generate-vapid-keys --json

TIP

For more details on the CLI, see web-push CLI documentation.

Step 2: Configure environment variable

VAPID_SUBJECT="mailto:email-notifications@kalisio.com"
VAPID_PUBLIC_KEY=<Your Public Key from Step 1>
VAPID_PRIVATE_KEY=<Your Private Key from Step 1>

Step 3: Configure the API

The KDK automatically sets up a Feathers.js service for push notifications when configured correctly. Update the API configuration to include the VAPID details.

Edit the app/api/config/default.cjs file to include the push notification configuration. Add the following push object:

module.exports = {
  // Other configurations...
  push: {
    vapidDetails: {
      subject: process.env.VAPID_SUBJECT,
      publicKey: process.env.VAPID_PUBLIC_KEY,
      privateKey: process.env.VAPID_PRIVATE_KEY
    },
    // By default, push service is not accessible externally
    disallowExternalPush: false
  }
  // Other configurations...
}

TIP

For a reference implementation, see kApp/api/config/default.cjs.

Step 4: Expose the VAPID public key in service capabilities

To allow clients to access the VAPID public key required for subscribing to push notifications, you need to expose it through the application's capabilities.

Edit the app/api/src/services.js file :

const response = {
    // Other
    vapidPublicKey: app.get('push').vapidDetails.publicKey
}

TIP

For a reference implementation, see kApp/api/src/services.js.

Step 5: Subscribe to push notifications in the client

To receive push notifications, the client must subscribe to the push service after user authentication. KDK provides a utility function to handle this subscription.

Modify the app/src/boot/kdk.js file to subscribe to push notifications after the user authenticates. Add the following code:

// Subscribe to webpush notifications
api.on('authenticated', (data) => {
// User will be updated in store just after login so that we need to wait for the event
Events.once('user-changed', utils.subscribeToPushNotifications)
})

TIP

For a reference implementation, see kApp/src/boot/kdk.js.

Step 6: Handle push notifications in the service worker

The service worker is responsible for receiving and displaying push notifications. Update the custom service worker file to handle push events and notification clicks.

Edit the app/src-pwa/custom-service-worker.js file to include the following code:

// Web push notification
let clickOpenUrl
self.addEventListener('push', event => {
  const pushOptions = event.data.json()
  clickOpenUrl = pushOptions.url
  // Show notification
  event.waitUntil(self.registration.showNotification(pushOptions.title, pushOptions))
})
self.addEventListener('notificationclick', event => {
  // Close notification if clicked
  event.notification.close()
  // Open window on the specified url
  if (clickOpenUrl) {
    const promiseChain = clients.openWindow(clickOpenUrl)
    event.waitUntil(promiseChain)
  }
})

TIP

For a reference implementation, see kApp/src-pwa/custom-service-worker.js.

Step 7: Sending push notifications

To send a push notification, use the push service created.

const pushService = app.getService('push')
pushService.create()

TIP

For more details, refer to the feathers-webpush documentation.