Back to writings

Short but Complete Guide to Web Push Notifications

·
6 min read
·189 views
Web Push
Notifications
Architecture
Web APIs
Cover Image for Short but Complete Guide to Web Push Notifications

When I first wanted to implement web push notifications, I was overwhelmed by the complexity. What I needed wasn't another implementation guide, but a clear mental model. This article provides that big picture, but it's really meant to complement the interactive demo that walks you through the implementation.

A Common Source of Confusion: Notification API vs Push API

Before diving into the architecture, let's clear up something that confused me at first: the difference between the Notification API and Push API. While they sound similar, they serve distinct purposes:

Notification API

Push API

These APIs must work together:

  1. Notification API gets permission
  2. Push API receives the message
  3. Service Worker uses Notification API to display it

📚 Related APIs

Understanding the Architecture

To understand web push notifications, it helps to break them down into three main areas:

  1. What happens in the browser
  2. What happens on your server
  3. How they communicate (through push services)

What Happens in the Browser

The browser is where most of the magic happens. It needs to:

This is accomplished through two main APIs:

1. Notification API

This is your bridge to the operating system's notification system:

📚 Related APIs and Resources

2. Service Worker

Think of this as your notification manager running in the background:

📚 Related APIs and Resources

What Happens on Your Server

Your server has a simpler but crucial role:

The main components here are:

1. Subscription Storage

2. Notification Trigger System

📚 Related APIs and Resources

How They Communicate: The Push Service Bridge

This is where VAPID (Voluntary Application Server Identification) protocol comes in. It's the secure bridge between your server and the user's browser:

Push Service

VAPID Protocol

This is the security layer that ensures only your server can send notifications to your users:

📚 Related APIs and Resources

The Journey of a Push Notification 🚀

Before we dive into the details of the flow, let's visualize how all these pieces interact:

Notification Journey

This diagram shows the complete lifecycle of a push notification, from initial setup to displaying a notification. Let's break down each phase in detail.

The Flow of a Notification

Now that we can see how the pieces interact, let's examine each phase more closely:

  1. Setup Phase (One-time)

    • Browser: Requests notification permission
    • Browser: Registers service worker
    • Browser: Gets subscription from push service using your public key
    • Your Server: Stores the subscription

  2. Sending Phase (Each notification)

    • Your Server: Prepares notification
    • Your Server: Signs with private key
    • Your Server → Push Service: Sends signed message
    • Push Service → Browser: Delivers to correct browser
    • Service Worker: Receives and displays notification

📚 Related APIs and Resources

Common Gotchas and Tips

📚 Debugging Resources

Ready to Implement?

Now that you understand where everything happens, head over to our interactive demo where we'll walk through implementing each piece step by step. The demo provides hands-on experience with:

Understanding these concepts will help you build more robust notification systems and debug issues more effectively when they arise.

Want to Go Deeper?

While writing this guide, I discovered an incredible resource that goes far beyond what we've covered here: The Web Push Book by Matt Gaunt. If you're interested in diving deeper into web push notifications, It's a fantastic next step after you've got the basics working with our demo.

If you enjoyed reading this, checkout my other writings:

all writings