Pushpad
Articles › Browser Support, Web Push Notifications

iOS special requirements for web push notifications

  • # ios
  • # safari
  • # web-notifications
  • # permission
  • # prompt

iOS has some additional requirements for web push notifications.

First requirement: Add to Home Screen

If your PWA is opened inside a browser tab on iOS, then the notifications are not supported. Please note that this is not a limitation of the Pushpad platform, this is a technical choice imposed by Apple.

The user needs to add your web app to their home screen before using web push.

Basically your PWA needs to be installed on the device before displaying the notification prompt.

From a technical point of view, when the user opens your web app in Safari, the browser does not support the Push API: this means that pushpad('unsupported') will trigger the callback, while all the other methods for web push, like pushpad('subscribe') or pushpad('widget'), will be ignored (no-op).

On the other hand, when the user installs your PWA and opens it using the icon on the home screen, then web push is supported and everything works normally.

However note that, even if the user has installed your PWA, when they open it from the browser, then the notifications are still considered unsupported: the Push API works normally inside the installed PWA, but it doesn't exist in the browser context. In particular, if a user opens your website in the browser, instead of using the PWA, then they are still considered not subscribed to notifications in that context. However that is a iOS limitation and you can't do anything to avoid that. Even the localStorage of the PWA is separate from that of the browser, so there isn't any workaround for this.

Add to Home Screen (solution)

The solution for this requirement is simply to ask users on iOS to add your PWA to Home Screen:

if (!window.matchMedia('(display-mode: standalone)').matches) {
  // the user opened your PWA in the browser...
  // display a message that asks the user to add your PWA to home screen
  // and to open it from there
}

Second requirement: User gesture

iOS requires that the call to display the permission prompt (e.g. pushpad('subscribe')) happens when the user clicks on a button, on a checkbox or something similar.

You cannot display the permission prompt for notifications on page load - that would be rejected and ignored.

User gesture (solution)

You should call pushpad('subscribe') during a click event (or similar):

document.querySelector('#subscribe-button').addEventListener('click', function() {
    pushpad('subscribe', function (isSubscribed) {
      // ...
    });
});

Otherwise you can use pushpad('widget'), which works even if you call it on page load, because it uses a double opt-in prompt. Or you can build your own custom prompt.