Web push notifications: issues and limitations

In this post, I will summarize some problems and constraints that I've encountered with the Notifications and Push web APIs.

Notification settings on macOS

Someone who's definitely not me wasted half an hour wondering why triggered notifications would not appear. On macOS, make sure to enable system notifications for your browsers. Open "System Settings" → "Notifications". For each browser, select "Allow notifications" and set the appearance to "Alerts":

Onchange listener not called

Web APIs offer a way to subscribe to change events. This is especially useful in React:

navigator.permissions
  .query({ name: "push", userVisibleOnly: true })
  .then((status) => {
    status.onchange = function () {
      // synchronize permission status with local state
      setNotificationPermission(this.state);
    };
  });

Whenever the notification permission changes (either through our application logic or via browser controls), we can synchronize the UI in real-time according to the current permission value (prompt, denied or granted).

However, due to a Firefox bug, the event listener callback is never called. This means that we can't react to permission changes via browser controls in Firefox. That's especially unfortunate when combined with push messages, where we want to subscribe the user once they grant the notification permission. One workaround is to check at page load if the notification permission is granted with no valid subscription and resubscribe the user.

Notification image not supported

Browser notifications support an optional image property. This property is marked as "experimental", so it's not surprising that some browsers (Firefox, Safari) don't support it. There is an open feature request to add support in Firefox, but it has been open since 2019.

VAPID contact information required

When sending a push message, we have to provide VAPID parameters (e.g. the public and private key). According to the specification, the sub property (contact email or link) is optional:

If the application server wishes to provide, the JWT MAY include a "sub" (Subject) claim.

Despite this specification, the Mozilla push message server will return an error if the subject is missing:

401 Unauthorized for (...) and subscription https://updates.push.services.mozilla.com/wpush/v2/…

You might not encounter this issue when using the popular web-push npm package, as its API encourages you to provide the subject as the first parameter:

webpush.setVapidDetails("hello@example.com", publicKey, privateKey);

However, in the webpush-java library, you need to set the subject explicitly:

builder.subject("hello@example.com");

There is an open issue with more information about this problem.

Microsoft Edge pitfalls

Microsoft introduced adaptive notification requests in the Edge browser. It is a crowdsourced score system, which may auto-accept or auto-reject notification requests. The behavior can be changed in the Edge notification settings.

Additionally, on a business or school device, those settings might be fixed, displaying the following tooltip:

This setting is managed by your organization.