PushizoDocs
Channels

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

  1. 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.
  2. subject: mailto:ops@pushizo.com or https://pushizo.com (push services use this address to reach you if there is a problem).
  3. Place PushizoSDKWorker.js at the site root and call Pushizo.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

BrowserStatusNote
Chrome, Edge, Opera, Brave (desktop/Android)FullImage (chrome_web_image), badge icon (chrome_web_badge), buttons (web_buttons)
FirefoxFullImages not supported; limited buttons
Safari macOS 16+FullStandard Web Push; icon taken from the site icon
Safari iOS/iPadOS 16.4+Only for PWAs added to the Home ScreeniOS 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 with collect: '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

FieldDescription
headings, contents, urlTitle, body, click URL (language map)
chrome_web_iconNotification icon (192×192 recommended)
chrome_web_imageLarge image (Chrome/Edge)
chrome_web_badgeMonochrome badge (Android Chrome)
web_buttons[{ id, text, url? }] up to 2–3 buttons
web_push_topicReplaces the previous notification with the same topic (Topic header)
require_interactionStays open until the user dismisses it
ttl, priorityTime 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.p256dh and keys.auth come from the browser subscription.
  • If the push service returns 404/410, the subscription becomes invalid and a subscription.invalidated webhook is emitted; the SDK re-registers it on the next launch with autoResubscribe.
  • If the user revokes permission in browser settings, pushSubscription.state.permission = 'denied'; the SDK reports this on config refresh.

Troubleshooting

SymptomCheck
Subscription is not createdHTTPS, PushizoSDKWorker.js returns 200 with the correct Content-Type, Pushizo.Debug.setLogLevel('debug') in the console
Notifications not arrivingDashboard Message Tracking → delivery status; if failed, check error_code (410 → subscription revoked)
Not arriving on SafarimacOS 16+ or an iOS PWA; Do Not Disturb/Focus mode
Icon not showingchrome_web_icon must be HTTPS and reachable

On this page