The Sorry State of Implementing Web Push Messages in 2024

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.
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.

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 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. 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 you entire domain is dedicated to your ‘app’ only, 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.
• 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 topics. If you only use a single topic, it's not that bad because most platforms will collapse all the duplicates into one notification anyhow, thanks to the tag being identical. However, “most” is not “all,” and the exception has a pretty large market share, see 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.
• The Instance ID (IID) for a client is a 22-byte 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 ‘:’. 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.
• 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 after invoking showNotification, not before. 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.
• 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.

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 resolves when all the work is done. Yes, you won't escape having to learn how to properly chain Promises.
  If you want to perform multiple tasks in the push handler that do not need to be sequential, you can create multiple Promises, and then use:
  event.waitUntil(Promise.all([promise1, promise2, etc])).
  One of those Promises must be the one that handles the showNotification.
  If you want to do something with a certain delay after receiving the push, don't just fire a setTimeout, it will be aborted if it lasts more than a few seconds. Wrap the timeout in a Promise. Even with the waitUntil, I suspect your service worker might be killed if it remains active for too long, but I haven't tested what is the limit, if there is 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.

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.
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.
   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 SW's 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.
   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 good strategy.
• Show a notification upon every incoming push, no matter what it contains, or iOS will punish you.
• When using FCM, the web app must do a getToken call at least once a month to prevent the token from becoming stale.
• 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.

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.
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, 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.