Notifications

Overview

The Notifications API provides a way to display native notifications with actions and to handle notification and action clicks. io.Connect Browser supports all available Notification settings as defined in the DOM Notifications API.

The io.Connect Browser Notifications API extends the DOM Notifications API with the option to handle notification and action clicks using Interop methods.

Configuration

Raising notifications without actions doesn't require any special setup of the Main app or the Browser Client apps.

If you want to raise a notification with actions, your Main app must register a Service Worker. There are two ways to register a Service Worker:

  1. Use the serviceWorker property of the configuration object for the @interopio/browser-platform library to provide the URL to the Service Worker file. The library will check the browser compatibility and register the Service Worker:
import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    serviceWorker: {
        url: "/service-worker.js"
    }
};

await IOBrowserPlatform(config);

Use this option if you don't need the Service Worker in your project for anything other than raising notifications with actions.

  1. Use the serviceWorker property of the configuration object for the @interopio/browser-platform library to provide the ServiceWorkerRegistration Promise returned from the registration of the Service Worker:
import IOBrowserPlatform from "@interopio/browser-platform";

const swPromise = navigator.serviceWorker.register("/service-worker.js");

const config = {
    licenseKey: "my-license-key",
    serviceWorker: {
        registrationPromise: swPromise
    }
};

await IOBrowserPlatform(config)

Use this option if you need access to the Service Worker in some other app-specific logic as well.

io.Connect Browser Worker

Defining a Service Worker is specific for each app and is outside the scope of io.Connect Browser. In order for an io.Connect Browser project to be able to correctly process notification actions and their respective click logic, you must include the @interopio/browser-worker package in your Service Worker file.

Initialization

The @interopio/browser-worker package exports a default factory function and additionally attaches it to the Service Worker global scope. This offers two options for consuming the library.

The first option is to use the importScripts function to add the io.Connect Browser Worker to the Service Worker scope and is suitable for basic Service Worker scripts:

importScripts("/web.worker.umd.js");

self.IOWorker();

The second option is to import the @interopio/browser-worker package in a dedicated Service Worker project the output of which will be a ready Service Worker script:

const IOWorker = require("@interopio/browser-worker");

IOWorker();

The IOWorker() function adds a listener to the notificationclick event and sets up the necessary communication between the worker and the Browser Platform. This enables the custom action click logic of io.Connect Browser notifications.

Configuration

The IOWorker() function accepts an optional configuration object. Use it to specify handlers for notification and action clicks, as well as whether the worker should open the Main app if it's closed when the user clicks the notification.

The configuration object has the following signature:

interface WebWorkerConfig {
    platform?: {
        url?: string;
        openIfMissing?: boolean;
    };
    notifications?: {
        defaultClick?: (event: Event, isPlatformOpened: boolean) => Promise<void>;
        actionClicks?: IOConnectNotificationClickHandler[];
    };
};

interface IOConnectNotificationClickHandler {
    handler: (event: Event, isPlatformOpened: boolean) => Promise<void>;
    action: string;
};

The WebWorkerConfig object has the following properties:

Property Type Description
platform object By default, the worker won't open the Main app when a notification is clicked. This property allows you to instruct the worker to open the Main app if it's closed when the user clicks the notification. Use the url property of the object to provide the location of the Main app. Use the openIfMissing property to specify whether to open the Main app if it's closed when the notification is clicked.
notifications object Allows you to specify custom logic that will be executed on notification or action click. Use the defaultClick property of the object to provide a function that will be executed when the user clicks the notification. Use the actionClicks property to provide a list of handlers that will be executed when the specified notification action is clicked.

The IOConnectNotificationClickHandler object has the following properties:

Property Type Description
handler function Handler for the notification action.
action string The title of the notification action for which the handler will be executed.

Functionality

The @interopio/browser-worker package exposes two additional functions - raiseIONotification() and openBrowserPlatform(). Both are attached to the Service Worker global scope and exported from the library.

  • openBrowserPlatform() - asynchronous function that accepts the URL to the Main app as an argument and resolves with void. Opens the Main app and waits for the @interopio/browser-platform library to be fully initialized and configured.

  • raiseIONotification() - this function has the same signature as the raise() method of the Notifications API. It's meant to be used if your project utilizes the Web Push Protocol. In such scenario, the Main app is likely not opened and therefore the Service Worker is responsible for displaying the notification.