Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

Notification Center overview

OpenFin Notification Center provides application developers with a uniform way to create and organize desktop notifications as well as respond to notification events (notification clicked, closed, etc). Notifications are displayed as toasts as well as listed and organized in a Notification Center. These notifications can be configured with buttons, icons, and categories. Notifications can also contain actions to help users stay up-to-date and notified of events within an OpenFin application.

The Notification Center is home to all OpenFin application notifications and is accessed by clicking on the Notification icon in the system tray.

Dependencies

Features

  • Create notifications
  • Persist notifications in the Notifications Center
  • Notifications can be configured to expire based on a set timeframe
  • Manually dismiss notifications
  • Attach handlers for click and close events
  • Application restart and passing of actions when an application is closed
  • Markdown and image (.ico files) support, within the notification body parameter (excludes code blocks & links)

Creating a notification

Creating a basic notification for Notification Center only takes a few lines of code. The following example show how to construct a basic notification using the title, body, and category properties. To create a notification, call the create() method with a few properties (title, body, category) in your main.js file.

create({
    title: '3 weeks to go until #FinJSatHome',
    body: 'Just three weeks left until #FinJSatHome! Join us to hear how web technologies are causing a revolution in the capital markets...',
    category: 'Event',
    buttons: [
        {
            title: 'Sign Up Now',
            onClick: {
                window.open("https://www.finjs.com/", "_blank")}
            }
        }
    ]
});

Sample Notification

Notification card created with basic propertiesNotification card created with basic properties

Notification card created with basic properties

Parts of a notification

A notification card, with its parts annotatedA notification card, with its parts annotated

A notification card, with its parts annotated

Properties

When the properties listed above (title, body, and category) are defined, the notification npm library constructs a notification. These properties, called NotificationOptions, define the content and configure actions for a notification. Some of the NotificationOptions properties are discussed here; for a full list of available properties, refer to NotificationOptions in the API reference.

title

This is the text displayed directly under the notification header in heading style.

body

  • This is the main notification content displayed below the main notification title. The body property may contain basic markdown syntax and images (.ico files).

πŸ“˜

Note

Links and code blocks are not supported in the body property.

expires

Notifications are set to persist in the Notifications Center app by default. However, a notification can be configured to expire by adding the expires property as a NotificationOption as shown below.

create({
    ...
    expires: date;
});

sticky

In addition to a notification card in the Notifications Center app, a notification also produces a pop-up "toast" on the desktop. In contrast to cards, toasts are transitory unless you use the sticky property with the sticky value (vs. the default value transient) to make them persist until the user dismisses them.

create({
    ...
    sticky: 'sticky';
});

πŸ“˜

Use with care

Avoid overwhelming the user with too many persistent toasts. Use this option only for really important notifications.

indicator

A notificationIndicator adds a colored banner at the top of the notification card or toast. An indicator consists of a text string summarizing the condition and an indicatorType, which can be one of the following:

  • FAILURE
    • Indicates a failure has occurred, usually from an action the user has taken
    • Shown as a red banner
  • WARNING
    • Warns a user that a significant event is occurring, for example, that they have a limited time to buy
    • Shown as an amber banner
  • SUCCESS
    • Tells the user that an item has been successful
    • Shown as a green banner

πŸ“˜

Note

The maximum size of NotificationIndicator.text is 32 characters.

category

Categories describe the context of a notification. This allows you as an application provider to control different types of notifications that are raised by your application based on context. For example, if you create calendar notifications you can categorize them for the end-user. Categories like Upcoming Events for notifications when an event is about to start and Event Start for notifications for when an event starts are helpful for the user, as they can distinguish what category the notification belongs to.

To set a category, add the category NotificationOption to the notification and set the value to a string.

Buttons

Notifications allow you to construct and control buttons within a notification. Configuration of ButtonOptions allows for an icon and button text to be added to a button, as well as onClick properties.
To create a button, provide a buttons property as part of the notification definition.

create({
    ...
    buttons: [
        {
            title: 'Snooze for 5 minutes',
            iconUrl: 'https://www.example.com/timer.png',
            onClick: {
                task: 'schedule-reminder',
                intervalMs: 5 * 60 * 1000
            }
        }
     ]
});

Actions

Actions are an integral property in creating a Notification system. Actions are how notifications send data back to their OpenFin host application. Notifications have a number of ways in which actions can be raised, typically through user interactions (for example, clicking a button). As an Application Provider, you decide if you want to implement ways to be informed of these raised interactions and their corresponding events.

Below is an example of a basic application configured with actions. This example constructs a notification, configures a button, and demonstrates configuring the application to listen for a notification action that triggers an event. Refer to NotificationActionsEvent for more information on configuring them.

import {addEventListener, create} from 'openfin-notifications';

// Create a notification with two buttons
create({
    title: 'Reminder',
    body: 'Event "Weekly Meeting" is starting soon...',
    category: 'Upcoming Events',

    // Use the 'customData' field to store metadata about the event
    customData: {
        eventId: '12345'
    },

    // register an 'onSelect' event to capture the user click event
    onSelect: {
        task: 'view-calendar-event',
        target: 'popup'
    },

    buttons: [
        // Button schedules another reminder for 5 minutes later 
        {
            title: 'Snooze for 5 minutes',
            iconUrl: 'https://www.example.com/timer.png',
            onClick: {
                task: 'schedule-reminder',
                intervalMs: 5 * 60 * 1000
            }
        },

        // Button closes notification and doesn't reprompt the user
        {
            title: 'Dismiss',
            iconUrl: 'https://www.example.com/cancel.png'
        }
    ]
});

// Create a listener that is called for each action
// Note: This handler is used for ALL actions, from ALL
// notifications that are created by this application.
addEventListener('notification-action', (event: NotificationActionEvent) => {
    const {
        result,
        notification
    } = event;

    if (result['task'] === 'view-calendar-event') {
        // Open a window with full details of the associated event
        openEventDetails(notification.customData.eventId, result['target']);
    } else if (result['task'] === 'schedule-reminder') {
        // Schedule a new notification
        scheduleReminder(
            notification.customData.eventId,
            Date.now() + result['intervalMs']
        );
    } // Etc...
});

Action Event

A event that is fired when a user interacts with a notification UI element is called a NotificationActionEvent.

πŸ“˜

Note

An application receives these events only if it has indicated that it wants to receive them.

The best way for an application to set a NotificationActionEvent is to create a listener for the initial notification-action done by the user. Creating a listener for a notification action allows the application to listen for new events and fire the consumed NotificationActionEvent, making a streamlined chain of call-and-response commands for notifications.

To create a NotificationActionEvent, add a listener to a notification-action as per the example below. This listens for the user to complete this action and complete the set NotificationActionEvent.

// Create a listener that is called for each action
// Note: This handler is used for ALL actions, from 
// ALL notifications that are created by this application.
addEventListener('notification-action', (event: NotificationActionEvent) => {
    const {result, notification} = event;

    if (result['task'] === 'your-apps-event') {
        // Open a window with full details of the associated event
        openEventDetails(notification.customData.eventId, result['target']);
    } else if (result['task'] === 'your-apps-reminder') {
        // Schedule a new notification
        scheduleReminder(notification.customData.eventId, Date.now() + result['intervalMs']);
    } // Etc...
});

Triggers

Notifications also permit triggers that can raise actions. Each action raised results in a NotificationActionEvent. For example, if you configure the select trigger with a NotificationActionEvent like the one above, when a user clicks on the body of the notification and none of the clicks hit a control or the close button, the set 'select' action is triggered.

App relaunch

Notifications allow configuring buttons that relaunch an application if it’s closed. For example, if an application is closed and the user views a notification from it, the user can click a button in the notification to relaunch the associated application.

To permit relaunch of an application

  1. Create a button (as shown in the code above)
  2. Configure it with the onSelect property and a corresponding action .

Known Issues

A list of known issues can be found on the versions page.

Updated 2 months ago


Notification Center overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.