The Sorry State of Implementing Web Push Messages in 2024–2026

Are You Prepared to Go Insane?

This article summarises what I learned from trying to implement the most trivial web push notification system possible, to let subscribers know when a new strip of my S.O.N.A.I.S webcomic has been published.

This is not a neatly structured guide, rather a semi-random collection of facts about implementing notifications using Web Push. You should look elsewhere for tutorials, but be aware that those tutorials will usually leave out the small but important details. This webpage is meant to provide many of those details.

In general, you will want to use some ready-to-use library or framework to add push notifications to your website or web app, that shields you from all the nitty-gritty details discussed here. This article is meant to help those who need to implement those frameworks, or the masochists like me who want to try implementing their own push message system from scratch.

If I have to summarise my experiences in a single meme, it will be this one, borrowed from the StackOverflow answer mentioned below:

This text was written after toiling for a whole month on creating a vaguely usable Web Push implementation, repeatedly moving from one frustration to another. Defying Sauron is peanuts in comparison. As a result, this article is full of sarcasm, bile, and some minor strong language. If you cannot handle that, then don't read it.

Update, August 2026: this article has been revised after a long overdue audit of my own implementation. Several problems previously blamed on FCM were likely at least partially self-inflicted, and worse, some of the advice I originally gave here about the push handler was actively harmful. Those parts have been corrected, and the pitfalls I fell into myself have been added; the new and rewritten bits are marked with “2026.” If I managed to walk into these holes while paying attention, so can you. The overall conclusion of the article is, alas, unchanged.

Introduction

My use case is very simple, almost trivial: I draw a web comic ‘S.O.N.A.I.S.’ that normally updates twice a week, but there may be extra strips sometimes, or I may want to take a break. I thought it would be convenient for whomever wants to read this comic, to get push notifications when a new strip is available. As far as use cases for push messages are concerned, this is about the simplest possible.

My goal: people can hit a subscribe button, there is nothing user-specific, subscriptions are not linked to logins, everyone is treated the same. Every subscriber will receive the exact same notification when a script on the server publishes a message to a single fixed topic. The same style of notification should always appear, even when the user is watching the main comic page, because I want a simple consistent user experience. When a user clicks/touches/punches the notification, always the same webpage opens. I would prefer the page to open in the user's browser of choice, but begrudgingly I would also find it acceptable if the page would open in an embedded browser inside a dedicated app-like thing. I don't even try to reload the page if they already have it open, because I consider it evil to touch someone's already open browser tabs, hence I always open a new window/tab.

As you can see, my goals do not consist of anything special, anything fancy. How hard could it be? As it proves, hard. Way too hard.

My general conclusion: implementing web push messages at this time, especially manually, is a surefire road to insanity. It took me an entire month to end up with an implementation that mostly works and which has no vague copy-pasted Cargo Cult I don't understand. Yet, still this implementation sometimes misbehaves for unknown reasons. On some devices, it works flawlessly. On other devices, it self-destructs very often and needs to be reanimated by the user for it to work again for a few more push messages, after which it will again break. I have no clue why, debugging this problem is as good as impossible, and the problem cannot be within my own code because it keeps working on other devices. 🤯
(2026: that last conclusion may be wrong, and it is exactly the kind of reasoning you should never trust—see the notification tag trap below. A bug that only bites when there is still an unread notification lying around, will keep on “working” on every device you actively test with, because you swipe away those notifications yourself. I identified three separate ways in which my own code could lose a notification. This does not let FCM off the hook, but I did owe it an apology for part of the accusations.)

I have little confidence in the system I created, and I had to slap all kinds of disclaimers on the subscription page after verifying that the remaining issues seem fundamentally impossible to fix. The service worker has only 22 kBytes of code, but each line has been sculpted and crafted over the course of a month, making this amongst the most expensive code I have ever written. This was not a satisfying endeavour at all. Luckily it's just a notification system for a comic I draw purely as a hobby. I wouldn't want to use this for anything truly serious—I wouldn't want to have to deal with infuriated customers.

Alternate conclusion: I do not want to do any job that involves writing web applications beyond the very sporadical tiny simple thing. I value my sanity too much.

There are proposals to make web push notifications less insane, but for the time being, a lot of hoop-jumping is the norm. Implementing Web Push is like navigating a minefield: something will explode at the least expected moments. And, people have done their utmost best to coerce you into walking straight through this minefield with no opportunity to evade it.

One could try to take cover behind some pre-made framework like Angular, but at some point your push messages will break, and it will be very helpful if your knowledge goes further than a bit of Cargo Cult where you mimicked commands from a YouTube video and deployed magical config files. Also, no framework will protect against the inconsistent ways in which different vendors have implemented service workers, PWAs, push messages and notifications, which leads to certain annoying problems for which no satisfactory solution can possibly be implemented, not even in the best of frameworks or libraries. Arguably the worst offender is Apple, which first demands that you wrap your web app inside a PWA, and then provides a bug-ridden PWA implementation which they already have tried to kill at least once. Apple probably sees PWAs as a nuisance that bypasses their app store, and they only provided an implementation because of peer pressure. Their PWA and Web Push implementation is rife with bugs and annoying limitations, and their motivation to fix these issues is very low.

Context

I decided to use Google's Firebase messaging, a.k.a. FCM, to handle the sending of messages. It has the convenient concept of ‘topics’ that matches my use case.
First, we create an app in the Firebase console. A specific instance of the ‘app’ running in someone's specific browser will then be assigned a token, which can be subscribed to a topic. When sending a message to the topic, the FCM server will then handle the fan-out of sending that message to each subscriber of the topic. It was exactly what I needed, and it all sounds good… in theory.

The first indications of things to come, became apparent when I started reading a guide on StackOverflow. The mere length of the answer, its lack of an ‘accepted’ state, and its concluding “One Does Not” meme which I replicated above, were not very encouraging. Still, I felt it was doable and I should be able to make it work within reasonable time. Unfortunately that SO answer proved to be just the tip of the iceberg.

I wanted to get FCM to work with minimal external dependencies. Most guides you will find, not only for push messaging but pretty much anything nowadays, will tell you to deploy utterly bloated framework X and then sprinkle it with some magic configuration, and then it will usually work and in the end you have no idea what you just did. The average web developer nowadays does not mind being dependent on external parties that create fancy libraries which hide all the complexities—I am not one of those people. I like to know how things work, and the fewer dependencies I have to import to get something to work, the happier I am. I have seen way too many things explode in the past due to those external developers creating bugs, or introducing breaking changes, or suddenly killing off the project.
Sure, if I would need to add web push to some existing product backed by a development team, I would choose for a framework right away, because going low-level would be insane in that case. I compare it to Kerbal Space Program. When I started playing it, I managed to perform a moon landing mission entirely manually, using rough calculations and wet-finger guesses, and a lot of trial-and-error and dead Kerbals. The satisfaction of finally seeing the capsule touch down after re-entry was immeasurable. But then I installed the MechJeb plug-in to automate a lot of the aspects for subsequent missions, because I wanted things to progress faster. However, all the experience I gained from my manual endeavours allowed me to notice when MechJeb was about to fail horribly, because I knew what it was trying to automate and what it was supposed to be doing and what not.
This very website is a hobby project that I want to keep pure and simple, and the push message use case seemed basic enough that it should be feasible to implement at a low level, with as added bonus that I would also learn how the whole system works and be more confident when delegating things to a framework. In the end, someone, for instance whoever has to implement those fancy frameworks, has to know the dirty details, and boy are they dirty indeed. I thought it could be useful to collect the dirty details I discovered on this journey.

I will now list a big steaming pile of pitfalls I have encountered, starting with things specific to FCM, then moving on to more general facts, and as grand finale, some iOS-specific things.

Quirks related to using Google's FCM as a messaging back-end

• Google's FCM insists on a separation between foreground and background messages. The problem is that its idea of what is considered foreground and background, is unclear. If it sees any page it believes to be “related” to the app to be in focus, it will try to send a message to that page, not the service worker. On top of that, FCM is a big pile of bugs, or perhaps dubious design decisions (arguably also bugs). Combine these 2 facts, and we end up with the following madness.
  If any webpage of your entire website is currently visible, FCM will not invoke onBackgroundMessage in your Service Worker. Instead, it will attempt to send a foreground message to that page, even if that page has no JavaScript whatsoever, let alone a messaging.onMessage handler, and even if that page is not within the scope of the SW. The latter is mind-boggling: I find it perfectly reasonable to expect that only pages within the SW's scope can be considered foreground, but the developers of FCM think otherwise.
  Therefore, you have 2 options to ensure your messages do not vanish into /dev/null:
  1. Load scripts with an onMessage handler in Every Single Page Of Your Entire Website; and handle the event in some appropriate way. Have fun! This might be OK if your entire domain is dedicated to your ‘app’ only (in other words, if it is a SPA), but not if your site hosts various loosely related things.
  2. Fight the system: forget about onMessage and onBackgroundMessage; instead add your own push event handler to the service worker, and sniff event.data.json() from the event. You can see whether it comes from FCM by looking for fcmMessageId. Then extract the data attribute as you would in onMessage, and Bob's your uncle. Unclear whether you would still need to provide dummy onBackgroundMessage and onMessage handlers—maybe not a bad idea, to ensure FCM really knows you expect messages. (2026: registering a dummy onBackgroundMessage has one concrete benefit, it stops FCM from conjuring up notifications of its own next to yours.)
     2026, two important amendments to the above. First, use fcmMessageId to recognise a message, never to decide whether to show one: a push you refuse to display is a push that can get your permission revoked, see the iOS section. Second, be careful with event.data.json(): see the payload parsing pitfall below.
• If you want to be able to send specific messages to individual users, you must maintain a user-token mapping, and each invocation of getToken must be followed by a check to compare the token to the last known one, as stored in an IndexedDB (or LocalStorage, but only IndexedDB is available to Service Workers). If the token is new or has changed, perform a call to your back-end to register/update the token in your database. If you're building something with Firebase, you could use the data store thingamajig it offers, but anything else will do.
  On the other hand, if you will never send user-specific messages, but you will only publish messages to topics which users can subscribe to, then in theory you should only keep track of what token wants to subscribe to what topic. Unless I overlooked something, there is no provision in front-end firebase JavaScript libraries to subscribe a token to a topic. This needs to be done from a firebase-admin instance in the back-end, for instance through the Python or NodeJS module. Hence even when you're only going to send messages through topics, you still need to keep a (possibly temporary) back-end store of token-topic mappings, and ensure that if a token has changed, it is re-registered; but it will be simpler because you only need to be concerned with subscribing newly added tokens to their desired topics—in theory.
• Ideally one should unsubscribe tokens from topics before deleting the tokens, if possible. Many guides say you don't need to, but my experiences tell otherwise. If you don't clean up things before a token is deleted, it seems possible for messages to keep on arriving at the client if a service worker is still running for your app, even if the user's current token is not subscribed to the topic. Or, the client may receive duplicate messages.
  This is obviously not how things should be; one would expect the FCM server to wipe the relevant IID-topic associations when deleteToken is invoked, but apparently this has bugs—oh what a surprise! These ghost subscriptions can accumulate, causing the same message to arrive multiple times if tokens have been repeatedly deleted before being unsubscribed. (This might be related to this issue on the FB GitHub, although it could also be another bug.)
  This can make things very messy if you're going to be using multiple FireBase topics. If you only use a single topic, it looks like you get off lightly, because most platforms will collapse any duplicates into one notification anyhow, thanks to their tag being identical. However, “most” is not “all,” and the exception has a pretty large market share, see below.
  2026: make sure to avoid giving notifications the same tag, deliberately or accidentally. The same mechanism that collapses duplicate pushes into a single notification, will happily collapse two legitimate, unrelated notifications into one as well, and it does so unnoticeably. See the tag trap below.
  You may be tempted to implement some extra logic in the service worker to suppress identical messages that arrive within a span of a few seconds. Likewise, if you use multiple topics, you may be tempted to try to be smart by encoding the topic in the message's tag, and suppressing incoming messages with non-matching topics. However, you should not implement any such things, because not showing a notification upon receiving a push, may get you in big trouble on iOS, see below. (And yes, of course iOS is that exception I mentioned above!) In other words, until this ghost notification bug is fixed, FCM topics are pretty much unusable for any serious application, period.
  What makes this particularly tricky, is that it is futile to try to write safeguards to unsubscribe tokens at the right moments—it won't help. I have seen tokens change all by themselves. The FCM website also mentions that one should be robust against tokens changing at any moment, for instance if some security problem has required tokens to be changed server-side. If the user messes with site data in their browser, FCM will for sure get a new token (and perhaps a whole new IID) the next time getToken is invoked. I have also noticed that the token can change when the user merely disables and then re-enables messaging permission for your site, even without doing anything in between. Hence it is pretty much inevitable that existing tokens will be invalidated without any chance of first unsubscribing them from a topic. Once the token is replaced by a new one, you can no longer unsubscribe the old one, because it will be “gone” and cause an INVALID_ARGUMENT or NOT_FOUND response. This makes sense because the token is supposed to be gone—except sometimes it isn't.
• Topics give you no delivery feedback whatsoever (2026). This makes their overall usefulness very debatable, and caused me to modify my back-end to send to individual tokens instead. When publishing to a topic, FCM answers with a message ID and nothing else. You do not learn how many tokens it fanned out to, which of them were UNREGISTERED or otherwise dead, or indeed whether a single soul received anything at all. Consequences: your back-end registry silently fills up with corpses that you have no way to identify, and when a subscriber reports “I got nothing,” you have literally no data to reason with. Sending to individual tokens instead (batched) gives you a result per token, which lets you prune the dead ones and, far more importantly, lets you tell the difference between “FCM refused to deliver this” and “the device received it and did not show it.”
  Google's own documentation also states that topic messages are optimised for throughput rather than latency, and recommends targeting registration tokens for single devices or small groups. And there is the rotation window: when FCM replaces a token, the new one is not subscribed to your topic until your back-end gets around to doing that, and anything published in the meantime is simply gone. For a mailing-list-sized audience, the convenience of topics stops being worth it very quickly.
• Sending pushes directly to tokens does not solve the unreliability problems (2026). So, I did modify my Python script that sends push messages, making it explicitly send to all known subscriber tokens in batches instead of sending to the topic. Result from the very first test: the same tablet that often failed to receive push messages sent to the topic, also never received this push message, despite running the robustified client code and despite Firebase explicitly returning an OK status for this token when the push was sent. A subsequent test message did arrive: the tablet had not lost its subscription.
  At best, explicitly pushing to tokens might be marginally more reliable than subscribing them to a topic and then pushing to the topic. But I have no concrete evidence for this, and in the end we are still like comparing between 2 diseases anyway. Hence I can only conclude that Firebase push messages are inherently unreliable on mobile devices, especially the more recent ones.
• The Instance ID (IID) for a client is an identifier string that represents a particular Firebase app on a particular client's browser. This IID can be found in the messaging tokens, it is the part before the colon ‘:’. (At the time of this writing, the IID is 22 bytes long, but it is possible that this will change.) It should remain the same for a given app on a client's browser, only the part after the : changes when tokens change. If any need arises to destroy this IID entirely, you can do that in firebase-admin, but it will take several days for it to be really gone, and the browser will keep on trying to use the old IID stored in certain IndexedDB instances for the website. I have seen no indications that this database is automatically wiped or reset when deleting the IID in the back-end. In other words, avoid deleting an IID unless it is really necessary. A reason might be that a user wants to keep using your app, but no longer wants to receive notifications from it, yet they still get these ghost notifications. If they insist on this being resolved, then you should try to obtain the user's IID and delete it entirely in the admin console. The user should also clear all your site data and re-initialise the app from a clean slate to be assigned a new IID. In general however, forcibly deleting an IID is to be avoided.
  If in your back-end store of messaging tokens, you encounter tokens with the same IID for the same topic, most likely all but the newest one will be invalid, caused by a glitch in the client's browser forcing FCM to generate a new token without cleaning up the old one.
• Do not make assumptions about the format of the token. When I created my first implementation, tokens had 140 characters following the IID and subsequent ‘:’ character. Around the end of 2024, this length suddenly had changed to 119 characters, and this broke some validation logic in my app. By the time you are reading this, the length may again have changed, and even the length of the IID might change.
• FCM caches the messaging token and some other user info in an IndexedDB. Only when this DB does not exist, or the caching/heartbeat period expires, will invoking getToken result in actual communication with the FCM servers. This is important to debug problems that only occur in that case: if you want to reproduce a bug that is only seen when FCM goes through the whole token creation workflow, you will need to delete those IndexedDBs to force getToken to phone home again. These IndexedDBs are easy to recognise, their names start with “firebase-”. At the time of this writing, there is a firebase-heartbeat-database, firebase-installations-database, and firebase-messaging-database.
• If your goal is to merely provide push messages that will not necessarily be opened by the user but usually swiped away, without the user interacting with your app, push messages could break after a few months because FCM must see some indication that the user's token is still in use, and this indication is getToken() being invoked often enough. If not, FCM could mark the token as “stale.” Documentation is vague about this, but I have seen a period of 2 months being mentioned as staleness threshold. Thanks to the caching, one cannot really invoke getToken too often, the IndexedDB will prevent unnecessary traffic. But, it can certainly be invoked not often enough.
  If you foresee that you will send more than one message per month, a good solution is to have the service worker invoke getToken() every time a push is received, and of course update the token in your back-end if it has changed. As will be explained below, this should be done strictly after the showNotification promise has resolved.
  (2026 correction: I originally suggested here that you could also do it in parallel with spawning the notification; don't do that: see the rewritten first bullet of the next section for the gory details.)
  If you rely purely on this strategy, and will not be sending a message during 2 months, everyone's token will become stale and they will no longer receive messages (unless they open your app within due time and it performs a getToken).
  In practice I have noticed that tokens can already vanish into thin air way sooner than the mythical 2-month or even 1-month period, if a device was not online a few times when a push message was being sent. I have seen tokens becoming invalid within about 10 days of their last getToken call succeeding. Besides the obvious explanation of Firebase being a big steaming pile of bugs, the local token caching could also have a hand in this. In the most unlucky case, you performed a getToken right at the end of the local cache period, and the FCM back-end did not see any sign of life for this token during that period. If the device is then offline for 10 days, or fails to refresh its token, then perhaps the token expiry period is reached in the back-end. I have no idea what the local caching period is, however. I suspect it might even be variable, based on some heuristics. My advice is therefore to invoke getToken as often as possible.
• An invisible push that triggers a getToken would help in the situation where there is nothing noteworthy to notify about during a period long enough for tokens to expire. However, as mentioned below, this is a total no-go in Safari, and on other platforms it can also have effects that are annoying for the users. You could try to use Periodic Sync, but forget about this: it also does not work in Safari, and even in other platforms it is designed to stop working exactly in this case where you need it the most—it is an anti-feature. The only thing you can do in this case, is to annoy all your users with a dummy message, to trigger their getToken() calls. Isn't this all so much fun?
  To make it even more fun, recent mobile operating systems are eager to remove permissions and data from apps which the user has not opened during some arbitrary period. Even if you want to create an app that only serves as a vehicle to show push messages, you will somehow have to convince users to open the app once in a while.
  2026 addition: and when they finally do open it, make sure that you actually notice. A PWA that people “open” is usually not loaded: it is resumed from the background, so your page load code never runs again and your one opportunity for a getToken passes by unused. Someone can faithfully open your app every week for a month and still end up with a stale token. Listen for visibilitychange on the document as well, throttled to something sane like once an hour, and let the service worker decide whether a refresh is actually due.
• I have noticed that when a new IID subscribes to a topic for the first time, they will generally not receive the first next message sent to the topic, only the subsequent messages will start arriving. I don't know whether this is just a plain initialisation bug in FCM, or it is time-related due to things needing to propagate in the FCM back-end. In the latter case it might help to subscribe new tokens as soon as possible, instead of right before you're about to send the next push. However, my gut feeling leans towards the ‘plain bug’ theory.
• FCM notifications do not work by default in the Brave browser. The user needs to go to brave://settings/privacy and explicitly enable “Use Google services for push messaging,” because the Brave developers believe notifications are evil.
• Even when taking care of all the above, I have noticed that on some devices, like my Nokia tablet with Chrome, tokens will simply self-destruct regularly way before the normal expiry time, I'm talking mere weeks or even days. When this problem occurs, notifications will be broken until the user somehow triggers a getToken, which in such cases will then almost always produce a token that differs from the last one. Of course the getToken cannot be initiated from a push message, because those will be broken. There is no rhyme or reason behind this failure and due to its random nature and long timespans, trying to debug it is only something an absolute masochist would attempt. I suspect all the annoying energy saving and privacy hooey that is being incorporated in recent Android releases might be to blame for this. I think Google is a big fan of the security/privacy approach illustrated in one of the strips of my comic.

On Android devices, you can see what is actually going on with FCM, by invoking the diagnostics page. On phones, this can be done by dialling *#*#426#*#*, although this will likely only work in phone apps distributed by Google.
On Android devices that have no phone hardware and on which no official phone app can be installed, you will need to enable developer mode and connect through ADB. Then this command can be run from the debugging host machine to invoke the same diagnostics tool:
adb shell am start -n com.google.android.gms/.gcm.GcmDiagnostics

Quirks of web push notification implementation in front-end JavaScript, and PWAs in general

• To conserve battery power, mobile platforms are eager to stop your service worker as quickly as possible, especially when it is awoken by a push message while the device is not in active use (screen is off).
  To reduce the risk of the worker being prematurely aborted while it is still reacting to the push event, it is paramount that you perform a waitUntil on the event, with a Promise that only settles when all the work is done. Yes, you won't escape having to learn how async JavaScript really works.
  Correction, 2026: this bullet used to recommend:
  event.waitUntil(Promise.all([promise1, promise2, etc]))
  with the showNotification promise as one of its members. Do not do that: it is a bad piece of advice. Promise.all rejects the instant the first of its members rejects; it does not wait for the others, and nothing cancels them either. And the moment the promise you handed to waitUntil settles (resolved or rejected), the browser does not care: your worker becomes a candidate for immediate termination. A failing back-end call, a hiccup in IndexedDB, or an FCM server having a bad day, can yank the rug from under a showNotification that had not finished yet. The result is a notification that never appears, or a cryptic “site has been updated in the background,” and on iOS a step closer to losing notification permissions.
  The infuriating part is that you will not see this on your development machine, because on a desktop showNotification completes long before the other tasks have properly started. You will see it on phones: rarely, unreproducibly, and only after you have shipped.
  The robust solution is boring, sequential, and paranoid: show the notification first, await it, and only then do the housekeeping. Wrap the whole as a promise given to waitUntil that can never reject. Once the notification is on screen, you have nothing left to protect; being killed halfway through a token refresh costs you nothing that the next push or the next app launch cannot repair. If you insist on running the housekeeping in parallel, use Promise.allSettled, never Promise.all. And note that your handler must not throw synchronously either, which is easier said than done, see below.
• If you want to do something with a certain delay after receiving the push, don't just fire a bare setTimeout, it will not have any protections against being aborted. Wrap the timeout in a Promise.
  In general however, I strongly advise against using setTimeout in a push handler, because it will suspend execution of your worker, greatly increasing the risk that it will not be resumed. This is especially the case when the push notification has woken the device (possibly also activating the screen). The device will then want to go back to low-power mode as soon as possible, and it may deem suspended tasks not worth resuming. You should finish all tasks in a push handler as soon as possible. Only if you're certain that the push handler is running on a desktop machine or something else with no extremely frugal power management, you may consider relying on a timeout, but even in that case it should never be longer than a few seconds.
• Parse the push payload as if it hates you (2026). Everything in a push handler runs on a hair trigger: a synchronous exception means the handler dies before showNotification is ever reached, which means no notification at all, no waitUntil, and iOS quietly sharpening its guillotine. Behold three traps in one innocent line, all of which I shipped:
  const payload = ('data' in event) ? event.data.json() : myFallback;
  • 'data' in event is always true. A PushEvent always has a data property (is simply null when the push carried no payload) and the in operator walks the prototype chain, where it dutifully finds the accessor. myFallback is dead code that will never run, and a payload-less push takes the handler down with a TypeError. Use if(! event.data) instead.
  • .json() throws on anything that is not valid JSON. An empty payload, a test message from some console, a stray sender: all fatal.
  • Valid JSON is not necessarily an object. If the payload happens to be a string, a number or null, then a follow-up check like 'data' in payload throws a TypeError of its own.
  Wrap the parsing in a try/catch, check the types, and when anything is off, show a generic “something went wrong” notification instead. It is mildly embarrassing towards your users, which is infinitely better than the alternative: silence, and/or a platform that concludes you are abusing invisible pushes.
• The notification tag is a loaded footgun (2026). Everybody knows the pleasant half of what a tag does: notifications with the same tag do not stack up, the new one replaces the old one. Almost no tutorial mentions the other half: that replacement is silent by default. No sound, no vibration, no screen wake-up, no heads-up banner, nothing. The new notification is quietly swapped in, and unless the user happens to be staring at their notification list at that exact moment, they will never know it arrived.
  To get the alert back you must also pass renotify: true. That option may only be used in combination with a non-empty tag (supply it without one and showNotification rejects with a TypeError and shows nothing at all). Chrome and Android honour renotify; Firefox ignores it; Safari's support is best described as “do not count on it.” So treat it as a safety net, not as the fix. The actual fix is to give every message its own unique tag, by means of a sequence number or timestamp if need be. Reuse a tag only when you genuinely mean “replace the older thing.”
  What makes this pitfall so vicious is the way it hides:
  • It is invisible while developing, if you click or swipe away every test notification you send yourself.
  • It is nearly invisible on desktop, for the same reason: people tend to keep their notification list clean.
  • It is very visible on phones, where notifications happily pile up unread for days.
  • Old devices can be immune: the silent-replacement-plus-renotify behaviour only arrived in Chrome 50, back in 2016.
  • Safari is immune too, but for the opposite reason: as described below, it does not replace same-tag notifications. Its non-compliance accidentally protects it.
  There is a very practical way to fall into this hole even when you do know about it. If you build your options by destructuring the payload:
  const { title, tag, link_url, ...options } = payload.data;
showNotification(title, { ...defaults, ...options });
  …then tag is no longer part of options, so every notification silently inherits whatever constant tag sits in your defaults, and each new message replaces the previous one. 🤦
• The badge icon that can be passed as parameter to showNotification, which will show up in newest Android versions in the status bar and inside the notifications list, must be a silhouette consisting of only white pixels on a transparent background (alpha channel). If the pixels are not white, your icon may end up being displayed in white on white backgrounds, making it invisible. A sensible size for the badge is 96x96 pixels, it is pointless to go above that. Keep the silhouette simple and recognisable.
  At this time I would stick with PNG for the file format. WebP is more efficient, but old devices may not support it, and we're only talking a few kB difference at most.
  As for the badge, icon, and image parameters that can be passed to showNotification, consider all of them as best effort. Every platform treats these differently, some platforms may not show any of them. Put all effort and information in the title and body text, and consider the rest as icing on the cake.
• clients.openWindow() seems to have a mind of its own, and if a user has deployed your page as a PWA, then sometimes the user will be sent to the PWA's start_page instead of the URL given as argument to openWindow. See this StackOverflow question for more details.
  This might or might not be caused by the requirement mentioned in MDN's documentation for openWindow: “At least one window in the app's origin must have transient activation.”
  The transient activation thing is shrouded in mystery. The use of vague wordings like “recently” in its description does not help (some say that in Chrome, “recently” is 5 seconds, but other browsers may use a different definition). However, anyone with a functioning brain would agree that the act of a user explicitly opening a service worker's notification, should suffice to grant transient activation status to this service worker. But, what I have noticed is that it can take a considerable time for the browser to react to the user punching the notification and the page actually being opened, hence it is not unthinkable that the mystic transient activation timeout is exceeded in some cases.
  My recommendation is to make sure your PWA's start page has a very obvious link to the page(s) the notifications should be sending users to, so when they get bitten by this weirdness, they can at least reach the desired page even if it is a bit confusing. You could also wrap additional duct tape around your scripts, to somehow detect when the user ends up on the PWA page and not the intended page, and then show a banner with a link to that page. Of course this complicates things enormously and introduces more risks of things breaking, which has proven to be a recurring theme while I started wading through the cesspool that is Web Push.
  As with many of the other issues with Web push, there is no rhyme or reason behind this. I had tested my implementation on various devices and it all seemed to work. I never encountered this issue in my tests. Then the very first colleague who volunteered to test it, bumped into this issue immediately, although he was also using Chrome on Android just like me. He might have been a victim of Chrome taking too long to activate, but I am not sure. If you can't stand things that make no sense, then don't even think about trying to implement web push messages, because you will go insane for sure.
• Sometimes mobile Chrome ends up in a state where Notification.permission stubbornly returns a value of default, which means as much as: “you're totally f*cked.” This value seems to have the same semantics as denied. When going to Chrome's settings while it is in this state, things make no sense. It might show that permission is set to “ask” for all sites, with no particular setting for your domain. In other words, it should allow invoking Notification.requestPermission() and getting the permission dialog, yet it won't. It will act as if the user has explicitly denied permissions for the site, even when they haven't.
  The only way to get out of this mess, seems to be to destroy any existing service workers and start over, possibly after kicking and punching Chrome into submission and perhaps rebooting the whole device. Of course from a user's perspective, this cannot be explained and if they end up in this situation, the chance that they will get notifications working on your site, will be practically nil.
  Also, mobile Chrome seems eager to delegate the notification permission to the first PWA deployed by your website, even if that PWA does not use notifications at all. I hope you're not planning to deploy multiple PWAs from your same website domain, because I can guarantee you it will be absolute hell, both for you and your users.
  I have a sneaking suspicion that Chrome may be leaning towards the same idea as iOS Safari has already implemented (see below), namely to restrict notification permission to PWA-deployed web apps only, but this is just a hunch of mine. I guess it's the price we have to pay for all the idiots who keep shoving notification pop-ups in our faces at the very instant we open their websites. It's why we cannot have nice things.
• Once a user has installed a PWA, then some browsers like Chrome in Android may send the user to the PWA when they follow any link on your site that leads to a page within the scope of the PWA. I have found no reliable way to prevent this. This behaviour was intended to be controllable with the url_handlers member in the manifest, which was later on deprecated in favour of the handle_links and scope_extensions members. Neither seems to have any usable support at the time of this writing. I have attempted to set the values in my manifest and it did nothing, I cannot control how browsers handle links on my very own site. The best I could do, is detect when pages are inappropriately opened inside the PWA, and then yet again show confusing banners to users, explaining what a goddamn clusterfuck this whole design is, and allowing them to go back to the expected UI page.
  To avoid this problem in the first place, I recommend trying to implement the whole web app such that it only really uses a single URL, being the PWA's scope path itself, perhaps with only query parameters that can vary. This makes it fundamentally impossible for the PWA's user interface to end up on an unexpected page.
• Do not let the messaging library become a single point of failure (2026). It is easy to forget that receiving a push needs no Firebase whatsoever. The push event, the decrypted payload and showNotification are all plain Web Push, implemented by the browser itself; FCM is only needed to create, refresh and delete tokens. Yet the standard boilerplate puts this at the very top of the service worker:
  importScripts("https://www.gstatic.com/firebasejs/…");
firebase.initializeApp({…}); const messaging = firebase.messaging();
  and every one of those lines is executed every single time the worker starts. If any of them throws (the script is not in the worker's script cache and the network is being the network, a privacy extension blocks gstatic.com, Google changes something), then the worker fails to evaluate, the push event is never delivered, and nothing is shown. On iOS this is a step towards losing your permission.
  So, wrap the import and the initialisation in a try/catch, and keep the push handler free of any dependency on the library. A broken Firebase then costs you a token refresh instead of the notification. Note that in a service worker you cannot postpone importScripts to the moment you need it: it may only be called during the initial evaluation of the script.
• IndexedDB is the only storage a service worker has, and it is a minefield of its own (2026). A few traps that may have cost me real notifications:
  • A promise that never settles is worse than one that rejects. Forget the error handler on indexedDB.open, and the promise your wrapper returns will hang silently forever. Inside a push handler, that means the promise you gave to waitUntil never settles either, and your worker is kept alive doing nothing until the browser loses patience. Handle onerror and onblocked, always.
  • Transactions auto-commit as soon as you stop queueing requests inside them, so a read-modify-write spread over two transactions is not atomic. Two pushes arriving together will cheerfully lose each other's updates.
  • You cannot start a new transaction inside an onupgradeneeded handler—you must reuse event.target.transaction. This one lies dormant until the day you bump your database version, which is the worst possible day for it to surface.
  • Cache the promise of the open database, not merely the resulting connection, otherwise two concurrent callers each open one and you leak a connection. That leaked connection will then block the deleteDatabase that your “reset everything and start over” button needs to perform, and as this article should have made abundantly clear by now, you will need such a button.
• Your offline caching can take your notifications down with it (2026). cache.addAll() is all-or-nothing: if one single URL in the list 404s, the entire promise rejects, and if you passed that promise to event.waitUntil in the install handler, then the service worker fails to install. No worker, no notifications, if you forgot you renamed a spinner GIF. Catch that failure and carry on regardless: for a notification app the worker is the product, and offline support is a nicety.
  While you are in there, remember that whatever you hand to event.respondWith() must resolve to an actual Response. Returning an Error object from your cache fallback turns a simple cache miss into a hard network error for the page. Mind that Response.error() is a static method: writing new Response.error() throws, because it is not a constructor, and if that happens inside your own try block you will never even see it happen.

iOS-specific quirks of web push—Here Be Dragons

Now comes the real fun part. Oh yes, it gets even worse.
FCM, or any kind of push messaging for that matter, inside Safari/iOS is a Royal Pain. Yes, even more pain than all the above. But given the market share of this platform, you will want to support it of course, so let's bring on the pain.

1. Requesting notification permission in Safari is also bound by the transient activation requirement, which Safari has implemented in its own specific way. The notification permission must be requested from within a user gesture handler (click, touch). This is something I actually like, I wish all browsers would enforce this to get rid of the stupid pop-ups when loading websites. (Although as someone who has lived on this planet for many decades, I can guarantee you it won't help much if at all: marketing parasites will then demand that developers implement glass screen pop-ups to beg for notification access, and the situation will get worse for everyone, as it has with the goddamn cookie consent nonsense.)
   It seems that at some point in the past, Safari had separate permissions for notifications and push messages. This no longer seems to be the case, I believe everything has now been lumped together in a single notification permission. Maybe on old iOS versions it is like this, but web push won't work on those anyhow.
2. Invoking FCM's getToken from within a service worker requires the worker registration to have a PushManager. This is only supported in fairly recent versions of Safari, see the MDN info page.
   You could work around this by doing all getToken calls inside front-end code, but believe me, you don't want to, because it greatly complicates things. Respect your own sanity, and simply tell users of obsolete iOS devices that they will need to pay more Apple tax for a new device.
3. But wait, it gets worse! On iOS, one can only request/get notification permission from within a PWA environment! (PWA = Progressive Web Application, basically a bookmark-on-steroids that can be installed as an icon on the home screen.) Forget about simply doing it in a regular browser tab. So, not only must permission be requested from a user gesture handler, it must also be from inside a PWA.
   Don't try to detect the browser/environment from user-agent strings, it is hopeless and futile. User-agent strings are DEAD. Do not write scripts that make hard decisions based on the user-agent string, it is a surefire way to shoot yourself in the foot. Just use the absence of PushManager in window as an indicator to show a prompt to users that if they are using an iOS device, they need to install the PWA. Don't try to guess whether the user is on an iOS device, most of them will know it themselves. The ones that don't, should not even attempt to dive into the Web Push cesspool.
   (2026, warning for the sleep-deprived: write that check as if(! ('PushManager' in window)), with those inner parentheses. if(! 'PushManager' in window) parses as (! 'PushManager') in window, i.e. false in window, which is always false. A feature check that can never trigger, and not a single warning anywhere. Ask me how I know.)
   What makes this even more fun, is that Apple seems to hate PWAs, likely because it's a way to bypass their app store. Apple has almost killed PWAs again in Safari at some point, but luckily there was enough protest to revert this decision. However, it does indicate that Apple will have very low incentive to fix bugs in their PWA implementation, and of course there are bugs.

   

4. And then it gets even worse! In MacOS Safari, one cannot deploy any PWAs at all. Hence, it does support PushManager inside Service workers in plain browser tabs, but only starting from Ventura. However, there is a big fat bug that will cause the service worker to have no valid PushManager at semi-random moments, for instance when it is first created, even if notification permissions have already been granted.
   Even if there is a pushManager property in the serviceWorkerRegistration object, it may be undefined. This breaks getToken().
   To work around this bug, the user must ‘reboot’ Safari, in other words close and reopen it after the SW has been created, and then it usually has the pushManager. Yes, really. This is how Apple writes software these days. The SW may again lose its pushManager at certain moments, like when a push message is received while Safari is closed (yes, somehow the service worker still runs even if Safari is closed, I guess it is never truly closed).
   <RANT> If you are extremely lucky, this bug is fixed by the time you're reading this, but my experience with Apple products since 1990 tells me you should not get your hopes up high. Apple bugs have a tendency to accumulate and never get fixed until they ditch the whole product and replace it with something else, and then this will again go through a similar process of gradually decaying into an unusable state. Just look at the iTunes/Music app on MacOS, it is a sad affair these days. </RANT>
5. For FCM v10.10 compat to work at all in Safari, you must use the scripts from www.gstatic.com. Do not use the minified scripts from cdnjs.cloudflare.com, they are entirely broken in Safari, both in MacOS and iOS. You will get an exception “TypeError: t is not a function” when trying to invoke getToken.
6. So, now you've jumped through the hoops of adding a manifest.json to your page/web app to make it deployable as a PWA, you have probably spent some days on learning how to handle caching in a PWA (you should), and instructed iOS users to install the PWA and then hit a button inside it to enable the notifications. Depending on what you actually want to do, things may now again get worse when it comes to iOS Safari, to which all the below observations apply:
   • The next fun thing you will discover, is that a PWA in iOS is almost entirely confined, sandboxed to its own environment. Unlike in Chrome and the like, one cannot access the PWA's service worker from a regular browser tab even if it is within scope. It would be useful to know when the user has deployed the PWA, to avoid that they deploy it twice, but only a few browsers currently have a half-assed implementation of getInstalledRelatedApps, and Safari is not one of them.
     Some things are cloned from the regular Safari browser environment into the PWA's sandboxed environment, but only at the moment the PWA is installed. Cookies in the PWA will be a clone of the cookies at the moment of PWA deployment, but will not be kept in sync with the regular Safari app afterwards!
     (I did not test whether LocalStorage or IndexedDB are cloned in a similar way, but I suspect they might be, you should verify this if it matters.)
   • Opening URLs from within the PWA (through links, in both Chrome and iOS Safari, or also clients.openWindow in iOS only) will show them inside an embedded browser thing inside the PWA, if they are not in the PWA's scope as defined in its manifest. (Do not confuse the PWA scope with the service worker scope, it is not the same.) If you forgot to properly define this scope, your PWA's UI pages may be replaced with other pages if the user follows links in the UI or opens a notification. Even if it is possible to navigate back to the UI page, at the least the user will be utterly confused and frustrated. You do not want this, hence make sure to properly set up the PWA's scope! Only pages related to the PWA's UI must be within the scope defined in the manifest.
   • However, in iOS Safari, there is a subtle discrepancy between hyperlinks followed from within the PWA pages, and pages opened through clients.openWindow() in the service worker, for instance inside the worker's notificationClick handler:
     1. Pages opened in the PWA's embedded browser as links from within the PWA itself, will have access to the PWA's service worker even if the page is not in the worker's scope. They can obtain the SW's registration by passing its scope as argument to getRegistration().
     2. Despite the fact that pages opened through clients.openWindow() open in the same PWA-embedded browser, they cannot obtain the service worker registration in the same way as described above. Why Apple, why? I expect that if the opened page is within the scope of the SW, it might have access to the SW, but I have not tested this, so don't trust my word for it.
7. Also, (currently) FCM does not work in the Apple XCode iOS simulator.
   getToken() will fail with something like:
   FirebaseError: Messaging: A problem occurred while subscribing the user to FCM: Request contains an invalid argument. (messaging/token-subscribe-failed).
   It's probably because the fake device has weird deviating identifiers which confuse FCM. Perhaps there is a way to simulate a push to your service worker inside the simulator, but I have not found any obvious way. You can already test some things in the simulator, but for a whole end-to-end test, you will need a real iOS device.
8. One cannot do invisible push messages in Safari. Do not try it: if your service worker does not show a notification within due time upon receiving a push, its notification privilege will be revoked. Maybe not immediately, but certainly after a few occurrences. Invoking showNotification must get the highest priority, do it as quickly as possible and before anything else that has any risk of failing. Also invoke it even if the incoming message is not as expected. It is arguably better to show a notification “something went wrong,” than ending up in the situation where all future notifications are silently broken because Safari decided to revoke the app's permissions.
   Even on other platforms this is the recommended approach, because they may also do things that confuse the user when a push does not result in a notification, for instance Chrome will show the cryptic message: “this site has been updated in the background.”
9. Safari (both in iOS and MacOS) does not honour the standard of replacing existing notifications that have the same tag as the old one. Notifications will keep piling up.
   (2026: there is a bitter irony here. Because Safari ignores tags, it is the one platform that is immune to the tag trap described above: it cannot silently swallow a notification by replacing it, because it never replaces anything. For once, Apple's non-compliance works in the user's favour. Do not let this fool you into thinking a constant tag is harmless: everywhere else, it is not.)
   This would not be a big deal, if FCM would not have bugs that can cause each sent push message to consistently result in multiple pushes being received by the client (see above). And again, rocks and hard places: you cannot filter out these duplicate pushes, because your service worker must show a notification upon every received push, or its permissions will be revoked.
   You might think: let's check for existing notifications by using getNotifications, and invoke close() calls on them. Denied! First of all, only iOS 17 or newer allows to obtain the list of notifications, but it is of no use: iOS will not honour any close calls on the objects obtained as such. So, the only thing you can do, is apologise in advance to your iOS users about the fact that they are likely to start seeing duplicate push messages after a while. Isn't all this just grand? It's as if it has been designed by a total sadist.
   Some brave soul has opened a WebKit bug about this, but I can almost guarantee that unless there is a change in management at Apple, it will never be fixed. Allowing an app to perform close() on notifications, would allow to approximate invisible push messages, which as shown above, Apple considers the spawn of the devil.
10. There is one upside about Safari: it does not need to be open for push messages to be displayed. But of course this also has downsides:
    • As mentioned above, mobile devices try to limit the runtime of service workers. Safari seems really stringent in this aspect when launching a worker in this ‘cold’ state to let it handle a push, and will stop it very quickly if there is no ongoing waitUntil anymore, so make sure you use this where needed.
    • On iOS, there is yet another magnificent Apple bug, present since 16.4 and still present in 17.4.1. If your PWA is not open at the time a push is received, and the user opens the notification, at first it will all seem fine: the PWA will be launched on-the-fly and the webpage linked from your notification will open in the PWA's embedded browser as expected.
      However, when the user then tries to go back to the PWA's main UI page by using the ‘Done’ button, they will get an empty blank page. The only way to fix this, is for the user to force close the whole PWA and re-launch it. There is no straightforward workaround, believe me, I have tried everything that did not require wrapping inordinate amounts of duct tape around the whole design.
      You can repair the PWA in the notificationclick handler by performing a clients.openWindow with its start page, but then you cannot open the page that was supposed to be opened by the notification, because by design it is forbidden to perform more than one openWindow call from a notificationclick handler. You would either need to somehow trigger opening the PWA page when ‘Done’ is pushed (if that is possible at all), or you could also fix the PWA page as described above, and then trigger a banner/toast in it, to prompt the user to open the page that was actually supposed to open. You cannot do this automatically with window.open(), because this also can only be performed ONCE from a user gesture handler.
      This is of course all a major hassle, and adds even more fragile logic to your whole app and degrades the user experience. Simpler is to advise your users to keep your app open at all times to avoid this bug, or when they do end up in this situation, explain them how they can perform the weird awkward gestures that allow to close apps.
      And again, don't expect this bug to get fixed within the rest of your lifetime. In fact nobody has filed this bug yet in WebKit AFAIK. If you feel lucky, you could help out poor developers like me by doing it, but make sure you have a clear-cut reproduction scenario handy.

Conclusion

If I have to condense all the above into one sentence, then it would be: “Web Push in its current state is an abomination, avoid it if you can.” I have littered this page with memes, which seems fitting because Web Push is sort of a meme in itself.

If you cannot avoid having to implement something using Web Push, then even though pretty much every aforementioned point is worth looking at, the most important take home messages are:

• You must enable deploying your web app as a PWA, otherwise it won't work in iOS.
• You must request notification permission from within a user gesture handler. This is a requirement on some platforms, and is also less annoying to users than triggering a consent dialog as soon as they open your site. Annoying your users is never a good strategy.
• Show a notification upon every incoming push, no matter what it contains, or iOS will punish you, and other platforms may annoy your users with cryptic warnings. Show it first, await it, and only then do anything else; and never allow the promise you pass to waitUntil to reject.
• Give every notification its own unique tag, and add renotify: true for good measure. On the platforms that do honour tags, a repeated tag replaces the previous notification without a sound, and your users will swear they never received anything.
• When using FCM, the web app must do a getToken call at least once a month to prevent the token from becoming stale. In practice I recommend at least once a week.
• Program the whole thing extremely defensively and never assume that an operation will always succeed, or that the thing will be in the same state as last time.
• Make sure you have a good grasp of async programming and Promises in JavaScript. Use waitUntil where needed. If you don't, then you are likely to create something that seems to work, but will fail unpredictably when actually deployed, and it will be a total pain to debug.
• Make the push handler as lean and fast as possible. Do not postpone tasks, epsecially not using setTimeout (unless in very specific circumstances).
• Before you blame the platform, re-read your own push handler. Twice. The platforms deserve most of the bile in this article, but I spent years attributing lost notifications to FCM that my own code may have received, displayed, and then silently thrown away. A bug that only manifests on someone else's device, in the field, days apart, is not automatically someone else's bug.
• No matter how meticulously you craft your code, on some devices your notifications will simply break randomly, unpredictably, invisibly, and there will be absolutely nothing you can do about it. Yay.

The sad thing is that it's not just Web Push which gives me an impression of being a hot mess. My general sentiment is that a lot of software nowadays is sliding down this slippery slope of becoming way too complicated, scattered across multiple vendors who have their own different interpretations of a standard. As a result, implementing something is like navigating a minefield in which the mines spontaneously change places at random moments. Nobody except an ever shrinking elite of geniuses has an over-arching vision, no mere mortal can explain all the intricacies of how certain projects work, or randomly fail to work. It's all frameworks stacked on top of frameworks—goddamn turtles all the way down.

Programming these days is all too often becoming like wizardry. Follow someone's magic book of magical formulas written in JSON and YAML, and utter some incantations in the latest trendy programming language. Once something nears maturity, deprecate it and replace it with something new that is again full of fresh bugs and mysteries. I am not surprised that nearly brand new airplanes basically fall apart mid-flight. It's not just Boeing, it's a sign of an underlying problem that permeates society as a whole. Instead of fixing a flat tyre, we reinvent the whole damn wheel every time and ignore all the associated costs of doing this.
Everything is full of bugs that are often hard to reproduce because they're caused by race conditions and async routines that are a total pain to debug. Often it are not the most correct tutorials and example code that are being replicated everywhere, it are the ones that were published first. And as someone who has done a master in A.I., if you believe A.I. will make it all easier and better, let me tell you that this is an utterly naïve idea, in fact things might get worse. We are making A.I. constructs spit out code that is generated using models trained on all this dodgy code written by humans who take shortcuts all the time. I already see this with ChatGPT and friends, it is very apt at producing total garbage with an air of utmost overconfidence, which I guess is why many are so impressed by it—it faithfully mimics typical human behaviour, but only superficially. It lacks the deeper understanding.

If you want to try out my attempt at producing a workable web push notification system, and read my own idiosyncratic web comic as a side effect, head over to S.O.N.A.I.S.