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
| Requirement | Description |
|---|---|
| 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. |
| HTTPS | Required everywhere except localhost. |
| Web app manifest | A linked manifest.webmanifest with display: standalone (or fullscreen, minimal-ui). Sites with display: browser cannot receive notifications. |
| Add to Home Screen | The user must tap Share → Add to Home Screen; on iOS, push is not available to a site open in a Safari tab. |
| User gesture | Notification.requestPermission() can only be called inside a tap/click handler; an automatic prompt (autoPrompt) is silently rejected on iOS. |
| Service worker | PushizoSDKWorker.js at the site root (SDK default /PushizoSDKWorker.js). |
| Web Push channel | Dashboard → 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()callsPushManager.subscribethrough the service worker and registers the subscription with Pushizo; it returnstrue/false. The subscription ID isPushizo.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: standalonemedia query (isStandalone) andnavigator.standalone; thebeforeinstallpromptevent 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
410and the subscription automatically becomesinvalid(visible in Message Tracking). allowLocalhostAsSecureOriginis only for desktop development; testing from an iOS device requires HTTPS (e.g. anngrok/cloudflaredtunnel 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_buttonsandrequire_interactionare 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
urlfield in the PWA window (notificationClickHandlerMatch/notificationClickHandlerActionbehave the same); anopenedevent and adelivery.openedwebhook are generated. If the target URL is outside the manifestscope, iOS opens it in Safari. - Delivery confirmation (
received) is reported in the service workerpushevent; 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 theInbox.unreadCount()value withnavigator.setAppBadge(n)if you like.
6. PWA limitations
| Limitation | Impact / recommendation |
|---|---|
| Push only in an app added to the Home Screen | In a Safari tab, permission === 'unsupported'; show the user the "Add to Home Screen" steps. |
| Permission only via a user gesture | autoPrompt: true and automatic slidedown acceptance do not grant permission on iOS; use a button. |
| No silent push | content_available (data) messages are not delivered on iOS web; send visible notifications. |
| Fixed icon | The manifest icon; no per-message icon/badge/image. |
| No action buttons | web_buttons is ignored; a click opens the notification's url. |
| Separate permission per PWA | A user who adds the same site twice gets two separate subscriptions; login merges them under the same user. |
| No background sync | The offline queue (localStorage) is flushed on the next launch. |
| Storage eviction | Safari 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
- On an iOS device, open the HTTPS address in Safari → Share → Add to Home Screen → launch the app from the Home Screen.
- Tap the "Allow notifications" button → system prompt → allow. A
web_pushrecord (device.os = iOS) appears in Dashboard → Subscriptions. - 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
openedappears in Message Tracking. - Troubleshooting:
permission: unsupported→ not added to the Home Screen, or iOS < 16.4; subscription not created → Web Push channel disabled (web.vapid_public_keyempty) or service worker 404; notifications not arriving → check the provider response in Message Tracking (410subscription revoked,401/403VAPID key changed).
Additional push channels
Amazon ADM, Windows WNS, fallback channel, smartwatch, live updates, carousel, VoIP and App Clip (ADR-0052).
iOS critical alerts, interruption levels and sound
This guide explains the aps fields Pushizo supports in iOS notifications, how to use ios_interruption_level (time-sensitive / critical) and how sound/volume behaves. Critical alerts require an entitlement that Apple grants only on application…