PushizoDocs
Channels

iOS Safari (16.4+) web push and PWA

On iOS 16.4 and later, Safari can send notifications to web apps added to the Home Screen (PWAs) using standard Web Push. The Pushizo Web SDK supports this flow without extra code; the difference is that the user must first add the site to the Home…

On iOS 16.4 and later, Safari can send notifications to web apps added to the Home Screen (PWAs) using standard Web Push. The Pushizo Web SDK supports this flow without extra code; the difference is that the user must first add the site to the Home Screen, and permission can only be requested through a user gesture. This guide covers the requirements, the Pushizo.Notifications.requestPermission flow and PWA limitations.

1. Requirements

RequirementDescription
iOS / iPadOS 16.4+Older versions have no PushManager; the SDK returns 'unsupported' for Pushizo.Notifications.permission. On macOS Safari 16+, adding to the Home Screen is not required.
HTTPSRequired everywhere except localhost.
Web app manifestA linked manifest.webmanifest with display: standalone (or fullscreen, minimal-ui). Sites with display: browser cannot receive notifications.
Add to Home ScreenThe user must tap Share → Add to Home Screen; on iOS, push is not available to a site open in a Safari tab.
User gestureNotification.requestPermission() can only be called inside a tap/click handler; an automatic prompt (autoPrompt) is silently rejected on iOS.
Service workerPushizoSDKWorker.js at the site root (SDK default /PushizoSDKWorker.js).
Web Push channelDashboard → Channels → Web Push enabled (the VAPID key is delivered as web.vapid_public_key in GET /sdk/v1/apps/{app_id}/config).

2. Manifest

{
  "name": "Mağaza",
  "short_name": "Mağaza",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#2563eb",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}
<link rel="manifest" href="/manifest.webmanifest" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-title" content="Mağaza" />
<link rel="apple-touch-icon" href="/icons/icon-180.png" />

start_url and scope must be on the same origin as the service worker scope (/). Safari uses the manifest icon as the notification icon; the chrome_web_icon field is ignored on iOS.

3. Service worker

PushizoSDKWorker.js at the site root:

const apiUrl = new URL(self.location.href).searchParams.get('apiUrl') || 'https://api.pushizo.com';
importScripts(`${apiUrl.replace(/\/$/, '')}/sdk-web/PushizoSDKWorker.js`);

If you already have a PWA service worker (e.g. for caching), add the same importScripts line to it and pass the file path with serviceWorkerPath in the init options; on iOS, using a single registration scope (/) is the safest choice.

4. Flow: add to Home Screen → permission → subscription

import Pushizo from '@pushizo/web';

await Pushizo.init({
  appId: 'app_…',
  apiUrl: 'https://api.pushizo.com',
  autoPrompt: false,                 // automatic prompts don't work on iOS; request with a button
  welcomeNotification: { disable: true }, // local welcome notification on first subscription (also shown on iOS; optional)
});

const ua = navigator.userAgent;
const isIOS = /iPhone|iPad|iPod/.test(ua) || (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
const isStandalone =
  window.matchMedia('(display-mode: standalone)').matches || (navigator as { standalone?: boolean }).standalone === true;

function renderPushState() {
  const permission = Pushizo.Notifications.permission; // 'default' | 'granted' | 'denied' | 'unsupported'

  if (permission === 'unsupported') {
    // iOS 16.4+ but not added to the Home Screen: no PushManager → show guidance
    if (isIOS && !isStandalone) showAddToHomeScreenHint();
    else showUnsupported();
    return;
  }
  if (permission === 'denied') {
    showSettingsHint(); // iOS: Settings → Notifications → <app name>
    return;
  }
  if (Pushizo.User.pushSubscription.optedIn) showSubscribed();
  else showSubscribeButton();
}

document.getElementById('subscribe')!.addEventListener('click', async () => {
  // Inside a user gesture: permission + subscription (POST /sdk/v1/apps/{appId}/subscriptions)
  const granted = await Pushizo.Notifications.requestPermission();
  if (granted) await Pushizo.login(currentUserId); // if the identity is known, link the device to the user
  renderPushState();
});

Pushizo.User.pushSubscription.addObserver(() => renderPushState());
renderPushState();

Notes:

  • When permission is granted, requestPermission() calls PushManager.subscribe through the service worker and registers the subscription with Pushizo; it returns true/false. The subscription ID is Pushizo.User.pushSubscription.id.
  • A direct Notifications.requestPermission() call is not affected by the prompt backoff schedule; Slidedown.promptPush(), however, follows the 3/7/30-day schedule. On iOS, the slidedown's "Subscribe" button also counts as a user gesture.
  • For the Add to Home Screen hint, check both the display-mode: standalone media query (isStandalone) and navigator.standalone; the beforeinstallprompt event does not exist in Safari.
  • If the user removes the PWA from the Home Screen, Apple ends the subscription; on the next send the provider returns 410 and the subscription automatically becomes invalid (visible in Message Tracking).
  • allowLocalhostAsSecureOrigin is only for desktop development; testing from an iOS device requires HTTPS (e.g. an ngrok/cloudflared tunnel or a LAN domain with a valid certificate).

5. Notification content and clicks

  • Safari uses the title, body and url; chrome_web_icon, chrome_web_badge, chrome_web_image, web_buttons and require_interaction are not applied on iOS (they are ignored without errors). Notifications with an image show text only on iOS.
  • Click: the service worker opens the address in the url field in the PWA window (notificationClickHandlerMatch/notificationClickHandlerAction behave the same); an opened event and a delivery.opened webhook are generated. If the target URL is outside the manifest scope, iOS opens it in Safari.
  • Delivery confirmation (received) is reported in the service worker push event; it works even when the PWA is closed.
  • Badge: iOS 16.4+ supports navigator.setAppBadge; the Pushizo SDK does not write badges, but you can show the Inbox.unreadCount() value with navigator.setAppBadge(n) if you like.

6. PWA limitations

LimitationImpact / recommendation
Push only in an app added to the Home ScreenIn a Safari tab, permission === 'unsupported'; show the user the "Add to Home Screen" steps.
Permission only via a user gestureautoPrompt: true and automatic slidedown acceptance do not grant permission on iOS; use a button.
No silent pushcontent_available (data) messages are not delivered on iOS web; send visible notifications.
Fixed iconThe manifest icon; no per-message icon/badge/image.
No action buttonsweb_buttons is ignored; a click opens the notification's url.
Separate permission per PWAA user who adds the same site twice gets two separate subscriptions; login merges them under the same user.
No background syncThe offline queue (localStorage) is flushed on the next launch.
Storage evictionSafari may delete site data unused for 7 days; if the hs:<appId> local state is deleted, the SDK syncs the subscription from the server on launch (autoResubscribe).

7. Verification

  1. On an iOS device, open the HTTPS address in Safari → Share → Add to Home Screen → launch the app from the Home Screen.
  2. Tap the "Allow notifications" button → system prompt → allow. A web_push record (device.os = iOS) appears in Dashboard → Subscriptions.
  3. Mark the record as a Test device and use Messages → Send test push. The notification appears on the lock screen; tapping it opens the PWA, and opened appears in Message Tracking.
  4. Troubleshooting: permission: unsupported → not added to the Home Screen, or iOS < 16.4; subscription not created → Web Push channel disabled (web.vapid_public_key empty) or service worker 404; notifications not arriving → check the provider response in Message Tracking (410 subscription revoked, 401/403 VAPID key changed).

On this page