PWA iOS Push Notification Review

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Executive Summary

​

Severity Summary

​

iOS PWA Push Notification Requirements (Research)

​

Key Requirements for iOS Push to Work

1. PWA must be installed to Home Screen — Push is not available in Safari browser tabs. The app must run in standalone or fullscreen display mode via Home Screen.
2. User must explicitly grant permission — iOS requires a user gesture (button tap) to trigger Notification.requestPermission(). Cannot be called on page load or in a passive context.
3. Service worker must be registered — The service worker that handles push events must be active before subscribing.
4. VAPID keys required — The applicationServerKey must be provided during pushManager.subscribe().
5. userVisibleOnly: true is mandatory — iOS enforces that every push must show a visible notification to the user.
6. Payload size limit: ~4 KB — iOS Safari enforces a strict ~4 KB limit on push payloads (more restrictive than Chrome’s ~4078 bytes).
7. No silent push — iOS does not support silent/background push in PWAs. Every push must display a notification.
8. No vibrate on iOS — The Vibration API is not supported on iOS. Setting vibrate in notification options is silently ignored, but won’t cause errors.
9. Notification actions limited — iOS Safari supports a maximum of 2 notification actions (buttons). Excess actions are silently dropped.
10. No image in notifications — iOS Safari does not support the image option in showNotification(). Only icon and badge are respected.
11. tag + renotify behavior — iOS supports tag for notification grouping, but renotify behavior may differ from Chrome.
12. Subscription can expire — iOS may invalidate push subscriptions when the PWA is removed from Home Screen or during OS updates. Re-subscription logic is important.
13. clients.openWindow() limitations — On iOS, clients.openWindow() from a notification click may not work reliably if the PWA is not already running. clients.matchAll() + client.focus() + client.navigate() is the preferred pattern.
14. No requireInteraction — iOS does not support requireInteraction. Notifications auto-dismiss after a system-determined timeout.

​

Safari/iOS-Specific Behavioral Notes

• Permission prompt timing: iOS shows the native permission prompt only on explicit user gesture. If called without a gesture, it silently returns 'denied' without showing a prompt.
• Subscription endpoint format: iOS uses Apple’s push service endpoints (web.push.apple.com), which differ from Google’s FCM endpoints. The web-push library handles this correctly.
• Service worker lifecycle: iOS Safari may terminate the service worker more aggressively than Chrome. The push event handler must use event.waitUntil() to ensure the notification is shown before termination.
• No background sync for push: Unlike Android, iOS does not keep the service worker alive for background operations. Push events are the only reliable way to wake the service worker.

​

Gap Analysis

​

CRITICAL Issues (Push Will Not Work on iOS)

​

1. No iOS-Specific PWA Install Requirement Guidance

“Push notifications are not supported in this browser. Try using Chrome, Firefox, or Edge.”

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

“To enable push notifications on iOS, install Encore Health OS to your Home Screen first: tap the Share button, then ‘Add to Home Screen’.“

​

2. Permission Request Without User Gesture (iOS Silent Denial)

1. User taps toggle switch
2. handleToggle(true) calls subscribe()
3. subscribe() checks state.permission (synchronous state from a previous render)
4. Calls requestPermission() — this may or may not be within the gesture context depending on timing

• Call Notification.requestPermission() directly in the click handler, before any async operations.
• Restructure to: request permission first (synchronously from the gesture), then subscribe.
• Consider a dedicated “Enable Notifications” button rather than a switch toggle, which makes the gesture-to-permission flow more explicit.

​

3. importScripts for sw-push.js May Not Load on iOS

• importScripts() is supported but the imported script must be served with the correct MIME type (application/javascript).
• More critically, if the sw-push.js file is not in the precache manifest or is cache-busted incorrectly, iOS may fail to load it when the service worker starts up after an OS/browser update.
• VitePWA with Workbox’s importScripts option injects the call into the generated SW, but the sw-push.js file is in /public/ and is not precached by default with a revision hash, meaning stale cache issues are possible.

• Add sw-push.js to the VitePWA includeAssets or add a cache-busting revision to prevent stale scripts.
• Better approach: inline the push handlers directly into the service worker using Workbox’s injectManifest mode, or use VitePWA’s plugins approach to inject custom SW code. This avoids importScripts entirely.
• At minimum, add sw-push.js to the precache manifest with a revision hash:

additionalManifestEntries: [
  { url: '/index.html', revision: buildId },
  { url: '/sw-push.js', revision: buildId },  // Add this
],

​

4. VAPID Keys Not Deployed (Configuration Blocker)

• The edge function returns 503 (“Push notifications not configured”)
• The frontend has no VITE_VAPID_PUBLIC_KEY, so subscribe() bails early with a toast error

1. Set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT as Supabase edge function secrets
2. Set VITE_VAPID_PUBLIC_KEY as a Vercel environment variable (all environments)
3. Add VITE_VAPID_PUBLIC_KEY to .env.local for development

​

HIGH Issues (Significant iOS UX/Reliability)

​

5. PwaInstallPrompt Uses beforeinstallprompt (Not Available on iOS)

• “Install Encore Health OS: Tap Share → Add to Home Screen”
• Show this banner prominently on the notification settings page and optionally on first visit

​

6. notificationclick Handler Uses client.navigate() — Not Supported Everywhere

• On iOS, client.navigate() may throw or silently fail in certain conditions (e.g., when the PWA was suspended by the OS).
• The code doesn’t have a try/catch around the navigate call.

// Wrap navigate in try/catch, fall back to openWindow
try {
  await client.focus();
  await client.navigate(url);
} catch (e) {
  // Fallback: open a new window
  if (clients.openWindow) {
    await clients.openWindow(url);
  }
}

​

7. vibrate, image, and requireInteraction Won’t Work on iOS

• vibrate: [100, 50, 100] — Not supported on iOS (Vibration API not available)
• image: data.image (line 39) — Not supported on iOS Safari
• requireInteraction: data.priority === 'high' — Not supported on iOS

• Document this as a known iOS limitation in the notification system
• On the server/edge function side, consider platform-aware payload construction (don’t send image for iOS endpoints if you’re tracking device type)
• Add a device_type or platform column to pf_push_subscriptions to enable platform-aware notification customization

​

8. No Re-Subscription Logic for Expired iOS Subscriptions

• The user removes and re-adds the PWA to Home Screen
• iOS updates or resets the push token
• The subscription simply expires (Apple doesn’t guarantee token stability)

• On mount, after finding an existing subscription, send a “verify” request to the server to check if the stored endpoint is still valid.
• If the server reports the endpoint is expired/missing, automatically re-subscribe.
• Add a periodic health check (e.g., once per session) that verifies the subscription is still active server-side.

​

MODERATE Issues

​

9. device_info Column Referenced But Doesn’t Exist on pf_push_subscriptions

metadata: { device: sub.device_info || 'unknown' }

metadata: { device: sub.user_agent || 'unknown' }

​

10. web-push Library Import via esm.sh May Have Deno Compatibility Issues

import webPush from 'https://esm.sh/web-push@3.6.7';

1. web-push internally uses crypto.createECDH(), crypto.createHmac(), etc. — Node-specific APIs
2. Deno’s Node compatibility layer covers many of these, but edge function environments may have restrictions
3. The esm.sh CDN may not correctly polyfill all Node crypto primitives for Deno

• Test the edge function in a local Deno environment to verify web-push works
• Consider using npm:web-push@3.6.7 import specifier instead (Supabase edge functions support npm: specifiers which have better Node compatibility)
• Actually, I see the VAPID_KEY_SETUP.md recommends npm:web-push@3.6.7 but the actual file uses https://esm.sh/web-push@3.6.7 — the npm: specifier is preferred for Supabase edge functions

​

11. send-push-notification Edge Function Has No Authentication/Authorization

1. Any authenticated user could send push notifications to any other user
2. If the function is somehow exposed, unauthenticated calls could send notifications

// Verify the caller is authenticated
const authHeader = req.headers.get('Authorization');
// For user-to-user: verify caller has permission to notify target user
// For system: verify service role key is used

​

LOW Issues

​

12. console.log Statements in Service Worker and Edge Functions

• Replace console statements in sw-push.js with structured logging or remove them
• Ensure the edge function uses only the logger utility consistently

​

13. Push Notification Settings “Learn More” Links to Chrome-Only Documentation

• Make the link platform-aware (detect iOS/Android/desktop and link to the appropriate documentation)
• Link to your own documentation page that covers all platforms

​

14. PushNotificationSettings “Permission Denied” Recovery Instructions Are Chrome-Specific

1. Click the lock icon in your browser’s address bar
2. Find “Notifications” in the site settings
3. Change from “Block” to “Allow”
4. Refresh this page

1. Open Settings app
2. Scroll to Safari (or the PWA name)
3. Tap Notifications
4. Enable notifications

​

Summary of Recommended Actions

​

Immediate (Before Shipping iOS Push)

​

Short-Term (Improve iOS Experience)

​

Longer-Term (Polish)

​

Additional Recommendations

​

Platform Detection Utility

// src/platform/pwa/utils/platformDetection.ts
export function isIOS(): boolean {
  return /iPad|iPhone|iPod/.test(navigator.userAgent) || 
    (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
}

export function isStandalonePWA(): boolean {
  return window.matchMedia('(display-mode: standalone)').matches || 
    (window.navigator as any).standalone === true;
}

export function isIOSSafariInBrowser(): boolean {
  return isIOS() && !isStandalonePWA();
}

export function canReceivePushNotifications(): boolean {
  // iOS: only in installed PWA
  if (isIOS()) {
    return isStandalonePWA() && 'PushManager' in window;
  }
  // Other platforms: check standard APIs
  return 'Notification' in window && 'serviceWorker' in navigator && 'PushManager' in window;
}

​

iOS Push Test Checklist

• VAPID keys deployed to Supabase secrets and Vercel env vars
• PWA installed to Home Screen on iOS 16.4+ device
• Permission prompt appears on button tap (not on page load)
• Subscription is created and stored in pf_push_subscriptions
• Test notification received and displayed on iOS
• Notification tap opens the app and navigates to correct URL
• Notification works when app is in background (not running)
• Subscription survives app restart
• Expired subscription is detected and user is prompted to re-subscribe
• Edge function correctly handles Apple push service endpoints

​

References

• Apple: Web Push for Safari
• Apple: Sending Web Push Notifications
• MDN: Push API
• web.dev: Push Notifications Overview
• W3C Push API Spec
• Can I Use: Push API