Skip to main content

Notification Center in a web browser

The Notification Center for web browsers enables you to provide a consistent notification experience across desktop and web platforms. You can integrate the Notification Center component into a web application that serves as a Here Core Web platform; client applications can send notifications to it as they would to Notification Center on the desktop.

Differences between web and desktop implementations​

The web implementation of Notification Center is a lightweight adaptation of the desktop implementation, designed to run within a web browser rather than as a standalone window. Key differences include:

  • Simplified architecture: The web implementation doesn't include controllers for window management, security handling, or data storage that are provided in the desktop version. Window management is provided by the web browser. As a platform provider, you must handle security and data storage yourself.
  • Integration method: Instead of launching as a separate window, the Notification Center renders within your web application's DOM as a web component.
  • Stateless by default: The web implementation starts empty and must be populated with data by your web application.
  • Packaging: The web implementation is distributed as npm packages rather than being hosted on the Here CDN.
  • Simplified user interface:
    • The web implementation does not support notification toasts on the desktop. Notifications appear only in the Notification Center UI.
    • Streams cannot be "popped out" in a separate window.
    • Only the height of the Notification Center component is responsive.
    • The only user setting that is available is a toggle for playing sounds when a notification is created.

Install the packages​

The web implementation of Notification Center is distributed as two separate npm packages:

  • @openfin/web-notifications: For platform owners integrating Notification Center into their web application
  • @openfin/web-notifications-client: For client applications that need to send notifications to the Notification Center

Install and import the appropriate package for the type of application you are developing.

Web platform owner responsibilities​

When using the web implementation of the Notification Center, the platform owner has additional responsibilities compared to the desktop implementation:

  • Showing and hiding the Notification Center: Provide a UI element (such as a bell icon) that users can interact with to show or hide the Notification Center.
  • Saving and restoring state: The web implementation doesn't persist its state automatically. Use the getSnapshot() and applySnapshot() methods to save and restore the state of the Notification Center.
  • Synchronizing across instances: If the same web application is open in multiple tabs or windows, ensure that notifications are synchronized across all instances.
  • Relaunching content: If an action on a notification requires launching content that isn't currently running, web Notification Center does not attempt to launch it. The platform must ensure that any content that might receive an action is running.

Set up the Notification Center in your web-based Here platform​

The Notification Center web implementation depends on the Core Web package for communication between client applications and the Notification Center web component. If you are developing a web-based Here platform, you likely already use the Core Web package to enable layouts and interoperability across web applications in different views.

If you have not done so already, you need to create a web broker to handle communication among web applications. Refer to Core Web for platform developers.

The @openfin/web-notifications package provides the user interface for the Notification Center as a web component, which can run inside the web page of the Here platform application, isolated from the host page by the shadow DOM. You provide an HTML element that is a container for the web component.

Initialize the fin context​

To add Notification Center to your web-based Here platform, you need to establish a connection to the web broker using the @openfin/core-web package. If you are already using the Core Web package for web-based interoperability, you already have code similar to the following:

import { connect } from '@openfin/core-web';

const fin = await connect({
  connectionInheritance: "disabled",
  options: {
    brokerUrl: `https://EXAMPLE.COM/WEB-BROKER`,
    timeout: 300000,
  }
});

Notice that the connect() method returns a fin object, which you then pass when initializing the Notification Center, as well as to access other objects and methods of the Core Web package.

Initialize the Notification Center​

The way that you start using the Notification Center is different for the web than on the desktop. Rather than calling the register() function to access the Notification service, you call initNotificationCenter().

Once you have the fin object, you can initialize the Notification Center in your web application. You pass it options, which include the following properties:

  • fincontext: the fin object.
  • serviceId: a unique identifier for the Notification Center instance, which must be used by client applications to connect to Notification Center.
  • container: an HTMLElement in which to load the Notification Center web component; the component is optimized for containers with a width of 345 pixels.
  • snapshot (optional): a previously-saved NotificationCenterSnapshot object containing the state of Notification Center, to be loaded when it starts up.
  • theme (optional): a set of color properties, same as color themes for desktop Here Core UI Components.
  • customSoundUrl (optional): a string containing the URL of a custom sound to play when a new notification is created. If one is not provided, Notification Center attempts to load the default notification.wav from the Here CDN. If cross-origin media files are blocked and no customSoundUrl is set, no sound is played, even if the user has enabled notification sounds in the settings panel. Note: Some audio formats may not be supported by all browsers. Be sure to check browser compatibility for your chosen audio format.
import { initNotificationCenter} from '@openfin/web-notifications';

// Get the container element where the Notification Center will be rendered; the ID is up to you and must exist in the platform app's HTML
const notificationCenterContainer = document.querySelector("#NOTIFICATION_CENTER_CONTAINER_ELEMENT_ID");

// Initialize the Notification Center
await initNotificationCenter({
  finContext: fin,
  serviceId: "UNIQUE-NOTIFICATION-CENTER-SERVICE-ID",
  container: notificationCenterContainer,
  theme: { // optional
    palette: {
      brandPrimary: "#641E55",
      brandSecondary: "#22151F",
      backgroundPrimary: "#FFFFFF",
      // Add other color properties as needed
    },
  },
  snapshot: {...some previously saved snapshot},
  customSoundUrl: "https://EXAMPLE.COM/NOTIFICATION.WEBM",
});

Save and restore Notification Center data​

When the Notification Center opens, users expect to see any previous data displayed. To enable this, you can save and restore a NotificationCenterSnapshot that records the current set of applications, streams, notifications, and reminders. You can pass a saved snapshot to initNotificationCenter(), as shown above. You can also restore a snapshot at any time with applySnapshot().

// Get the current state of the Notification Center
const currentSnapshot = getSnapshot();

// Store `currentSnapshot` at your discretion
// Pass the saved snapshot when initializing

// Apply a previously saved snapshot of the state of Notification Center
await applySnapshot({...some previously saved snapshot});

Listen to Notification Center activity​

You can add or remove listeners for when the number of notifications changes, and for when the Notification Center component is shown or hidden, either by the user or by your code using the show() and hide() methods.

import {
  addNotificationCountListener,
  removeNotificationCountListener,
  addVisibilityListener,
  removeVisibilityListener,
  show,
  hide
 } from '@openfin/web-notifications';

Connect client applications to the Notification Center​

Client applications that are displayed using web layouts need to connect to both the web broker and the Notification Center before they can send notifications.

A client application is also referred to as a "notification provider" because it generates notifications.

The client application must explicitly connect to the Notification Center, and provide the following information about itself:

  • id: A string that identifies the client application; this ID must not change between sessions, so that its notifications are managed consistently.
  • title: A string with a user-friendly name for the application to display in the Notification Center UI.
  • icon (optional): A string containing a URL for an icon to display for the application.

In addition, the client must pass the fin object returned by the web broker and a serviceId value that matches the one used to initialize the Notification Center instance.

import { connectToNotifications, create } from '@openfin/web-notifications-client';

// First, establish a connection to the web broker as shown above in "Initialize the fin context"
// ...

// Connect to the Notification Center
await connectToNotifications({
  id: 'NOTIFICATION-PROVIDER-APP-UNIQUE-ID',
  title: "NOTIFICATION APP TITLE",
  icon: "https://EXAMPLE.COM/icon.png",
  serviceId: "UNIQUE-NOTIFICATION-CENTER-SERVICE-ID", // Must match the serviceId used during initialization
  finContext: fin
});

// Now you can use the Notification Center API, as on the desktop
await create({...});

If you want the same client app to work seamlessly with both the desktop and web implementations, you need a bit of conditional code to connect to the correct one, based on the app's environment. If the @openfin/web-notifications-client library receives a configuration with environment: 'desktop', it automatically works correctly with the desktop notifications service.

import { create, connectToNotifications } from '@openfin/web-notifications-client';
import { connect } from '@openfin/core-web';

let config;
if (typeof fin === 'undefined') {
  // Currently in a web environment
  const finContext = await connect({
    connectionInheritance: 'disabled',
    options: {
      brokerUrl: `https://EXAMPLE.COM/WEB-BROKER`,
      timeout: 300000,
    }
  });
   config = {
     environment: 'web',
     serviceId: 'UNIQUE-NC-CHANNEL-NAME',
     id: 'UNIQUE-APP-ID',
     title: 'APPLICATION TITLE',
     finContext
   }
} else {
  // Currently in a desktop environment
  config = {
    environment: 'desktop',
    finContext: fin
  }
}

await connectToNotifications(config);

// use the regular Notification Center API methods.
await create(...);

Create notifications​

After connecting to the Notification Center, client applications can create notifications using the same create() function as in the desktop implementation.

Manage notifications​

Client applications can manage notifications using the following methods:

import { 
  getAll, 
  update, 
  clear, 
  clearAll 
} from '@openfin/web-notifications-client';

// Get all notifications
const notifications = await getAll();

// Update an existing notification
await update({
  id: "EXISTING-NOTIFICATION-ID",
  title: "UPDATED TITLE",
  body: "UPDATED CONTENT"
});

// Clear a specific notification
await clear("NOTIFICATION-ID-TO-CLEAR");

// Clear all notifications
await clearAll();

Listen for events​

Client applications can listen for events triggered by user interactions with notifications:

import { 
  addNotificationActionListener,
  addNotificationClearListener,
  addNotificationCountListener
} from '@openfin/web-notifications-client';

Table of Contents