Web Push
The VAPID-based browser push channel — setup, browser support, service worker, permission prompts, content fields and troubleshooting.
Web Push travels through the browser's push service (Chrome/Edge → FCM, Firefox → Mozilla, Safari → APNs); Pushizo signs messages with your app's VAPID key pair. The user side is handled by the Web SDK; setup is covered in the Web quickstart.
Setup
- App settings → Channels → Web Push → Enable. The VAPID pair is generated automatically; the public key is delivered to the SDK via
GET /sdk/v1/apps/{app_id}/config, and the private key is stored encrypted and cannot be read back. subject:mailto:ops@pushizo.comorhttps://pushizo.com(push services use this address to reach you if there is a problem).- Place
PushizoSDKWorker.jsat the site root and callPushizo.init({ appId })on the page.
API: PUT /v1/apps/{app_id}/channels/web_push { "provider": "vapid", "config": { "subject": "mailto:…" } }; validation with POST …/channels/web_push/validate returns active immediately.
Security: the subscription endpoint sent by the browser is only allowed on known push service domains (SSRF protection); for self-hosted or additional push services, define the WEB_PUSH_EXTRA_HOSTS list in the server environment.
Browser support
| Browser | Status | Note |
|---|---|---|
| Chrome, Edge, Opera, Brave (desktop/Android) | Full | Image (chrome_web_image), badge icon (chrome_web_badge), buttons (web_buttons) |
| Firefox | Full | Images not supported; limited buttons |
| Safari macOS 16+ | Full | Standard Web Push; icon taken from the site icon |
| Safari iOS/iPadOS 16.4+ | Only for PWAs added to the Home Screen | iOS web push and PWA |
HTTPS is required; for localhost development, use allowLocalhostAsSecureOrigin: true.
Permission prompts
The browser's native prompt can only be opened by a user gesture, and a denial cannot be undone; so show a soft prompt first:
- Slidedown:
init({ slidedown: { enabled: true, delaySeconds: 5, pageViews: 2, retryDays: 7, title, message, acceptText, cancelText } }); collect email/SMS withcollect: 'email' | 'sms' | 'email_sms'. - Bell: a button in the bottom right/left corner that shows the subscription status.
- Custom link: call
Pushizo.Notifications.requestPermission()from your own button. - Backoff schedule: a denied/dismissed prompt is shown again after
promptOptions.backoffDays(default 3, 7, 30 days).
Dashboard → Channels → Web Push → Permission prompt designer configures the slidedown text and timing; the SDK downloads it with the config.
Content fields
| Field | Description |
|---|---|
headings, contents, url | Title, body, click URL (language map) |
chrome_web_icon | Notification icon (192×192 recommended) |
chrome_web_image | Large image (Chrome/Edge) |
chrome_web_badge | Monochrome badge (Android Chrome) |
web_buttons | [{ id, text, url? }] up to 2–3 buttons |
web_push_topic | Replaces the previous notification with the same topic (Topic header) |
require_interaction | Stays open until the user dismisses it |
ttl, priority | Time to wait in the push service (seconds) and Urgency |
A notification click focuses an open tab or opens a new one, controlled by notificationClickHandlerMatch / notificationClickHandlerAction; the click is recorded as opened and the display as received (the service worker reports to the API with token_hash).
Subscription lifecycle
- The subscription is registered with
GET /sdk/v1/apps/{app_id}/subscriptions;endpoint,keys.p256dhandkeys.authcome from the browser subscription. - If the push service returns
404/410, the subscription becomesinvalidand asubscription.invalidatedwebhook is emitted; the SDK re-registers it on the next launch withautoResubscribe. - If the user revokes permission in browser settings,
pushSubscription.state.permission = 'denied'; the SDK reports this on config refresh.
Troubleshooting
| Symptom | Check |
|---|---|
| Subscription is not created | HTTPS, PushizoSDKWorker.js returns 200 with the correct Content-Type, Pushizo.Debug.setLogLevel('debug') in the console |
| Notifications not arriving | Dashboard Message Tracking → delivery status; if failed, check error_code (410 → subscription revoked) |
| Not arriving on Safari | macOS 16+ or an iOS PWA; Do Not Disturb/Focus mode |
| Icon not showing | chrome_web_icon must be HTTPS and reachable |
Channels overview
The channels Pushizo supports (Web Push, iOS, Android, Huawei, email, SMS, WhatsApp, RCS, in-app, notification inbox, Live Activities), their providers and setup requirements.
iOS Push (APNs)
The APNs channel — .p8/.p12 credentials, sandbox/production environments, iOS content fields, badge/sound/category, Notification Service Extension and troubleshooting.