Skip to content
All integrations

Browser push (VAPID)

Browser push lets SafeOS Guardian wake the OS notification center even when the app isn't in focus. The PWA can show in-tab notifications without any server setup; this page covers backgrounded push, which needs VAPID keys on the API server.

Generate VAPID keys

VAPID keys identify your server to the browser's push service (Mozilla, Apple, Google). Generate a pair with the web-push CLI (already a SafeOS dependency):

npx web-push generate-vapid-keys

Then add them to your API server's .env:

VAPID_PUBLIC_KEY=BPxxxxxx...
VAPID_PRIVATE_KEY=xxxxxx...
VAPID_EMAIL=admin@yourdomain.com

VAPID_EMAIL is contact info for the push service — use a real address.

User-side opt-in

  1. Open SafeOS in a browser that supports push (Chrome, Edge, Firefox, Safari 16+).
  2. Accept the notification permission prompt when it appears (or open Settings → Notifications and enable browser push manually).
  3. For best results on mobile, install the PWA: Add to Home Screen on iOS, or Install app on Android.

iOS limitations

Apple supports web push only when the PWA is installed to the home screen and only in iOS 16.4+. Background push cannot work in a normal Safari tab. If a user can't install, fall back to email or SMS alerts.

Reference: web.dev push notifications overview.