Notifications

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.

General Notification Settings

Available since io.Connect Browser 3.2

To specify global notification settings, use the notifications property of the configuration object for initializing the @interopio/browser-platform library:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    notifications: {
        enable: true,
        enableToasts: false,
        clearNotificationOnClick: false
    }
};

const { io } = await IOBrowserPlatform(config);

The notifications object has the following properties:

The sourceFilter object has the following properties:

Notifications with Actions

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

If you want to raise a notification with actions however, 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 initializing 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"
    }
};

const { io } = 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.

2. 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
    }
};

const { io } = await IOBrowserPlatform(config);

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

Default Notification Handlers

In each Browser Client app (and also in the Main app) you can define default handlers for notification and action clicks. The appropriate handlers will be called when the notification or the action is clicked. Use the notification property of the configuration object for the @interopio/browser library to specify default notification handlers.

Browser Client apps:

import IOBrowser from "@interopio/browser";

const config = {
    notifications: {
        defaultClick: (io, notificationDefinition) => console.log("The notification was clicked."),
        actionClicks: [
            {
                action: "openClientPortfolio",
                handler: (io, notificationDefinition) => console.log("A notification action was clicked.")
            }
        ]
    }
};

const io = await IOBrowser(config);

Main app:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    browser: {
        notifications: {
            defaultClick: (io, notificationDefinition) => console.log("The notification was clicked."),
            actionClicks: [
                {
                    action: "openClientPortfolio",
                    handler: (io, notificationDefinition) => console.log("A notification action was clicked.")
                }
            ]
        }
    }
};

const { io } = await IOBrowserPlatform(config);

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:

The IOConnectNotificationClickHandler object has the following properties:

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.