Web Notifications (Native)

Overview

Native Web Notification

Native Web Notifications are desktop-level alerts delivered through the browser, even when the application is not actively in focus. These notifications utilize the Web Notifications API and provide an effective way to keep users informed about important events, such as process completions or system errors.

Servoy enables developers to use this functionality via the plugins.webnotificationsNative API, which offers features like permission management, support detection, and notification customization.

To be able to use Native Web Notifications, the Web Notifications package must be added from Services section of Servoy Package Manager. It can be accessed by code using plugins.webnotificationsNative.

Key Features:

• Permission Management: Determine and request user permission for displaying notifications.

• Support Detection: Check if the browser supports Web Notifications.

• Customizable Alerts: Define notification titles, bodies, icons, and click behaviors.

Use Cases

Native Web Notifications are useful in scenarios where critical or time-sensitive information needs to be conveyed to users outside the application's active session. Common use cases include:

• Process Completion: Notify users when a batch update or a report generation is finished.

• Reminders or Alerts: Send timely notifications about system errors, deadlines, or scheduled tasks.

• User Engagement: Draw attention to important updates or actions required in the application.

Examples

Checking Permission and Requesting Access

This example demonstrates how to check if the browser supports Web Notifications, determine the current permission status, and request permission if it hasn’t been granted yet.

if (!plugins.webnotificationsNative.isSupported()) {
    application.output("Web Notifications are not supported by this browser.");
} else {
    if (plugins.webnotificationsNative.getPermission() === "default") {
        plugins.webnotificationsNative.requestPermission(function () {
            application.output("Permission status: " + plugins.webnotificationsNative.getPermission());
        });
    }
}

Explanation:

• Check Support: The isSupported() method determines if the browser supports Web Notifications.

  • If not supported, the application logs a message and skips further processing.

• Check Permission: The getPermission() method retrieves the current permission status. It can return:

  • default: Permission has not yet been requested.

  • denied: User explicitly denied permission.

  • granted: User granted permission.

• Request Permission: If the status is default, the requestPermission() method prompts the user for access.

  • A callback function is executed after the user responds, logging the updated permission status.

Displaying a Notification

This example shows how to display a notification if the user has already granted permission.

if (plugins.webnotificationsNative.getPermission() === "granted") {
    plugins.webnotificationsNative.show(
        "Process Completed", 
        "Your batch update has finished successfully.", 
        "https://example.com/icon.png", 
        null, 
        "processCompleteTag", 
        function (tag) {
            application.output("Notification clicked: " + tag);
        }
    );
} else {
    application.output("Notifications are not permitted.");
}

Explanation:

• Check Permission: The getPermission() method ensures notifications are permitted. If not, it logs a message and does nothing.
• Show Notification: The show() method is called with the following parameters:

  • Title ("Process Completed"): The main text shown in the notification.

  • Body ("Your batch update has finished successfully."): Additional information displayed under the title.

  • Icon ("https://example.com/icon.png"): An optional URL to an image shown alongside the notification.

  • Image (null): A larger optional image to include in the notification body.

  • Tag ("processCompleteTag"): A unique identifier for the notification. If omitted, one is auto-generated.

  • Click Callback: A function that executes when the user clicks on the notification, logging the tag of the clicked notification.

Handling Notification Clicks

This example highlights how to trigger actions when the user interacts with a notification.

plugins.webnotificationsNative.show(
    "Reminder", 
    "You have a task due today.", 
    "https://example.com/reminder-icon.png", 
    null, 
    "taskReminder", 
    function (tag) {
        application.output("Notification clicked! Tag: " + tag);
        // Perform an action, e.g., navigate to a specific form or task.
    }
);

Explanation:

• Show Notification: Similar to the previous example, the show() method displays a notification with the provided title, body, icon, and tag.

  • Title: "Reminder", the main heading of the notification.

  • Body: "You have a task due today.", an informative message for the user.

  • Icon: A URL pointing to a visual icon representing the notification.

  • Tag: "taskReminder", a custom identifier for the notification.

• Click Behavior: The onClickCallbackMethod (function (tag)) defines a function executed when the user clicks on the notification.

  • Logs the tag of the clicked notification.

  • Placeholder for additional actions, such as opening a specific form or navigating to a task.