Introduction to Web Push Notifications and Alerts

Push notifications are a powerful engagement tool for modern websites and Progressive Web Apps (PWAs), allowing you to send real-time alerts, updates, and messages to users even when they aren't actively browsing your site. However, because spammy or poorly designed notifications can quickly annoy users, browsers enforce strict controls around the Web Notifications API. Websites must request permission before showing alerts, and notifications must be formatted correctly. Our online Notification API Permission Tester provides an interactive sandbox to test these features. You can request permissions, send mock local alerts, customize payloads (including titles, bodies, badges, and icons), and verify support. This diagnostic utility runs entirely client-side. To test notifications now, visit the tester at /devicelab/developer-tools/notification-api-tester.

How the Web Notifications API Works in Javascript

The Web Notifications API is accessed via the global Notification object in JavaScript. To check if notifications are supported, developers query ('Notification' in window). To check active permissions, they inspect Notification.permission, which returns 'default' (not yet asked), 'granted', or 'denied'. To request permission, they call Notification.requestPermission(), which triggers the browser's native dialog prompt. Once permission is granted, a new notification is instantiated by calling new Notification('Alert Title', { body: 'Message content' }). This executes a local system notification that displays on the user's desktop or mobile notification panel, complete with optional icons and badges.

Customizing Notification Payloads: Icons, Badges, and Sounds

The Notifications API supports several properties within its options object to customize how alerts appear to users. The 'body' property contains the main text message. The 'icon' property accepts a URL to a small image to display next to the title (such as a company logo). The 'badge' is a small monochrome icon used on mobile status bars when notifications are collapsed. The 'data' field can store arbitrary metadata linked to the notification, which is retrieved when the user clicks the alert. The 'tag' attribute acts as a unique ID; if a new notification is sent with the same tag as an active alert, the new notification will replace the old one, preventing multiple duplicate alerts from stacking on screen.

Integrating Notifications with Service Workers for Push Delivery

While local notifications are triggered by scripts running in an active browser tab, true push notifications are delivered when the website is closed. This is achieved by integrating the Notifications API with Service Workers and the Push API. A Service Worker runs in the background of the user's device. When your backend server sends a push payload via a push service (such as Firebase Cloud Messaging or WebPush), the Service Worker intercepts the push event and calls self.registration.showNotification() to display the alert. This integration is the foundation of modern PWA engagement, and our tester provides detailed logs showing how Service Workers handle these push payloads.

Troubleshooting Notification Failures and System Blocks

If you try to trigger a notification in our tester and nothing happens, several security and operating system settings could be blocking the alerts. First, make sure you have granted permission; check the lock icon in the URL bar to verify permissions. Second, check your operating system settings. On Windows, Focus Assist or Do Not Disturb settings can block all incoming desktop notifications, even if the browser has permission. On macOS, you must grant permission for your browser (Chrome or Safari) to show notifications in System Settings > Notifications. Finally, some browsers on mobile devices restrict push notifications to PWAs that have been explicitly added to the device's home screen. Checking these settings will help resolve delivery issues.