Web Push Notifications: Notifications API & Service Worker Integration

A user leaves the site — we lose them. Push notifications (using the Notifications API and Push API) bring back up to 30% of visitors, but implementing has pitfalls: browser blocking, Service Worker errors, incompatibility with some devices. We have implemented notifications for 15+ projects over 5+ years and know how to do it without pain. On one large e-commerce site, integrating push notifications with a custom Service Worker increased return rate by 28% in the first month. At the same time, we avoided typical mistakes: requesting permission after a click, correct handling of notificationclick, and a fallback for iOS.

Why Notifications API Needs a Service Worker?

The Notifications API and Push API are distinct. The former shows a notification through the browser, the latter delivers an event from the server. For notifications when the tab is closed, you need both. A Service Worker is mandatory: it runs in the background and intercepts push events. Without it, notifications only appear when the page is open. The Notifications API allows web pages to display system notifications (MDN). Over 95% of browsers support the API, but for push notifications you also need the Push API. Our React hook for Notifications API and Push API reduces code by half compared to manual implementation.

How to Request Permission and Not Get Blocked?

The main rule is to request permission only after an explicit user action, otherwise the browser will automatically block the request:

async function requestNotificationPermission(): Promise<NotificationPermission> { if (!('Notification' in window)) { throw new Error('Notifications API not supported') } if (Notification.permission === 'granted') return 'granted' if (Notification.permission === 'denied') return 'denied' // Call only from event handler (click, submit, etc.) return Notification.requestPermission() } 

Displaying a Notification: On the Page and via Service Worker

For displaying a notification on an open page, use new Notification():

interface NotificationOptions { title: string body?: string icon?: string badge?: string tag?: string // Grouping — new notification replaces old one with same tag requireInteraction?: boolean // Do not auto-close data?: unknown actions?: NotificationAction[] // Buttons in notification (Service Worker only) } function showNotification(options: NotificationOptions): Notification | null { if (Notification.permission !== 'granted') return null const { title, ...rest } = options const notification = new Notification(title, rest) notification.onclick = (event) => { event.preventDefault() window.focus() notification.close() // Navigate based on notification.data } return notification } 

For notifications when the tab is closed — only through Service Worker:

// service-worker.ts self.addEventListener('push', (event: PushEvent) => { const data = event.data?.json() ?? {} event.waitUntil( self.registration.showNotification(data.title ?? 'New notification', { body: data.body, icon: '/icons/notification-icon-192.png', badge: '/icons/badge-72.png', tag: data.tag ?? 'default', data: { url: data.url }, actions: [ { action: 'open', title: 'Open' }, { action: 'dismiss', title: 'Close' }, ], }) ) }) self.addEventListener('notificationclick', (event: NotificationEvent) => { event.notification.close() if (event.action === 'dismiss') return const url = event.notification.data?.url ?? '/' event.waitUntil( clients.matchAll({ type: 'window' }).then((windowClients) => { const existingClient = windowClients.find((c) => c.url === url) if (existingClient) return existingClient.focus() return clients.openWindow(url) }) ) }) 

React Integration

function useNotifications() { const [permission, setPermission] = useState<NotificationPermission>( typeof Notification !== 'undefined' ? Notification.permission : 'denied' ) const [supported] = useState(() => 'Notification' in window) const request = useCallback(async () => { if (!supported) return const result = await requestNotificationPermission() setPermission(result) }, [supported]) const notify = useCallback( (options: NotificationOptions) => { if (permission !== 'granted') return null return showNotification(options) }, [permission] ) return { supported, permission, request, notify } } 

function NotificationSettings() { const { supported, permission, request, notify } = useNotifications() if (!supported) { return <p>Notifications are not supported by your browser</p> } return ( <div> {permission === 'default' && ( <button onClick={request}>Enable notifications</button> )} {permission === 'granted' && ( <button onClick={() => notify({ title: 'Test', body: 'Notifications work' })}> Test </button> )} {permission === 'denied' && ( <p>Notifications are blocked. Enable in browser settings.</p> )} </div> ) } 

Push API and Comparison