Feature request: Teach iOS users to A2HS/Push

“Add to Home Screen“ (A2HS) has been a feature of iOS since the original launch of iPhone. But it’s never been very clear to users how to do it (or why anyone should).

Coming soon in iOS 16.4, iOS will support push notifications, but not for just any web site. It only works when you’ve “installed” the web app as an “app” via A2HS.

So! I think it would make sense for Discourse to explain to users how to A2HS and then sign up for push.

In iOS 16.4, to sign up for push, you have to:

  1. Scroll to reveal the URL bar
  2. Tap the (unlabeled) Share button (the box with an up arrow)
  3. Scroll the Share Sheet to reveal the A2HS button (and it’s not at all obvious that the sheet is scrollable!)
  4. Tap on “Add to Home Screen”
  5. Tap the “Add” button in the upper right corner (preferably without renaming the app)
  6. Return to your Home Screen, find the new app icon you just made, (which may be on a secondary Home Screen, so you might have to search for it by name, e.g. “Meta”) and tap on it
  7. Sign in again. (The A2HS PWA doesn’t share cookies with Safari, so if you sign in with Facebook, you also have to login with Facebook from scratch, including two-factor authentication and “Trust This Browser”.)
  8. Tap the banner to sign up for push

This will be extremely difficult for users to figure out!

Discourse should provide a link explaining how to A2HS and sign up for Push, preferably including a video tutorial showing how to do this, step by step.

Worse, I think it can’t just be one video tutorial. Much depends on whether you’re doing it on iPhone or iPad, whether your device has a Home button or not, etc.

Still, I think a feature like this would really help a lot for onboarding users to push notifications.


Since Apple shoot down the beforeinstallprompt event this is indeed quite involved on their platform.

This will be a problem for every webapp, so we may learn from what others are doing and try to use something that’s familiar for users.

People eager to start pushing for it can experiment with a theme component to help their users find the functionality.


iOS 16.4 is out now, and so I think this issue is now more urgent.


Perhaps an interim step to test the waters is a theme component?

Have it pop up some sort of dismissable dialog that walks you through how to do this? I guess open questions are:

  • Can iOS detect that it is in PWA vs not PWA?
  • What would the mechanics be for “reminding people to PWA”. (how long to wait? how often to annoy? Do you require people are TL1 for example?)
1 Like

Yes, and we already have a method for this in sniff-caps

There is already a banner in Android that trigger for TL1+

Clicking no is persisted to local storage.

Main issue here is that Apple was brought here against it’s will, so clicking on the install won’t trigger a install, but all we can do is show a modal with a tutorial of how it works. There is no community consensus around the modal appearance.


I just updated to 16.4 and…

“Push API” is not selected in experimental features. I think this is pretty much “dead in the water” till Apple enable this by default.

1 Like

That’s a common misconception. The “Push API” feature flag does nothing in 16.4. Push API works out of the box, enabled by default on iOS 16.4 (but only once you A2HS).

(I speculate that feature flag maybe will one day enable Web Push directly in Safari, without A2HS, but that feature doesn’t exist today, so turning the flag on/off does nothing.)

Go on and try it! You’ll receive a push, even with the flag disabled.


I see … well I just added to home screen … will see what this does.

1 Like

Don’t forget to follow all the steps I documented above. Tap on the A2HS PWA, sign in there, and then Enable Notifications via the banner. You should receive a test push right away.


As we already ascertained in the other topic that setting doesn’t refer to Web Push and has in fact been kicking around under experimental settings since iOS 15.4.

After the PWA has been added users only need to log back in and then enable notifications from their profile within the PWA.


One area of push back I have here is that the Discourse Hub app is still a tiny bit superior to the PWA

  • Multiple sites in one
  • Push notifications for all our hosted customers
  • No need to log in a second time due to auth handover protocol
  • Share link in footer instead of just back/forward
  • Easier to install (arguably)

That said … this is great progress, for sure! It is super usable :+1:

This kind of solidifies that the experiment with the loud nagging and teaching should be in a theme component (with an optional mode for teach about hub vs teach about pwa). Also makes me wonder if we can teach Hub just to lean on web push notifications as well for self hosted…

1 Like

IMO, the only advantage that Discourse Hub has right now is that it’s easier to (learn how to) install. Discourse Hub is an app, and everybody knows how to install an app. In Hub, you’d then have to paste in the forum URL, but there’s UI holding your hand through the process. Whereas the iOS A2HS process is… non discoverable. (Hence this thread!)

“Multiple sites in one” is actually a drawback for my tastes. (But, if you’re interested in it, it is now possible to rewrite Discourse Hub as a PWA! :exploding_head:)

“Push notifications for all our hosted customers” applies equally to Web Push, right? And even non-hosted customers get instant push with iOS 16.4 Web Push, whereas when I’d add non-hosted forums to iOS Discourse Hub, it would have to poll my non-hosted forums periodically, introducing delays.

“No need to log in a second time” … I just use “Sign in with Apple” and I’d say the experience is equally good for A2HS Web Push as it was in the Discourse Hub. I click Login, Apple scans my face, and I’m in.

“Share link in footer” I’m sure I’ve never used that! :wink:


Yeah sort of, we would lose a bit of chrome, the “collapse” to everything view (downwards triangle) would have to be implemented elsewhere. I don’t think you have control over buttons in the footer?

Also that is a can of worms cause we would would need to vet which sites we allow on the “web hub” and which are not allowed which will introduce regular work given there are upwards of 37k sites out there.

Yes… ideally Apple give us APIs just to lean on web push from apps so we no longer depend on being an arbitrar of notifications.

We are actually partially blocked here till we amend some internal auth stuff. If you have 2fa enabled you can not use 3rd party auth. We don’t allow both and internally we have a policy that all accounts of staff have 2fa on both dev and meta. We will change this… but not this week.

1 Like

That should be possible to the PWA, no? I use another PWA on iOS that has its own custom footer.

1 Like

Just an update here :smile:

We released an official theme component today that will be shown to iOS users on iPhone or iPad, encouraging them to install the Forum to their home screen as a PWA.


4 posts were merged into an existing topic: iOS Add To Homescreen Popup

I’ve continued the conversation on the theme component’s thread. I agree that it seems wiser for the default text to mention that A2HS is required for push notifications.