Scrum4Me/docs/patterns/web-push.md

title	status	audience	language	last_updated	when_to_read
Web Push	active	ai-agent contributor	nl	2026-05-07	When sending push notifications from the server or MCP layer, or when troubleshooting PWA push on iOS.

Patroon: Web Push

Wat & wanneer

Gebruik Web Push voor OS-niveau notificaties die ook verschijnen wanneer de browser-tab gesloten is (b.v. Claude-vragen, sprint-completion). Gebruik het niet voor in-app realtime feedback — daarvoor dient de SSE/realtime/notifications-stack (stores/notifications-store).

Architectuur

MCP / cron
  │
  ▼
POST /api/internal/push/send   ← Bearer: INTERNAL_PUSH_SECRET
  │
  ▼
lib/push-server.ts → sendPushToUser(userId, payload)
  │  • VAPID-check (disabled = warn + return)
  │  • prisma.pushSubscription.findMany
  │  • Promise.allSettled(sendOne[])
  │  • 404/410 → auto-delete stale subscription
  ▼
Web Push Service (FCM / APNS)
  │
  ▼
public/sw.js  →  showNotification + notificationclick

Payload-shape

type PushPayload = {
  title: string   // max 80 tekens
  body:  string   // max 300 tekens
  url:   string   // absoluut pad ('/dashboard') of volledige URL
  tag?:  string   // dedupliceert notificaties met dezelfde tag
}

Foutcodes

Code	Betekenis	Actie
404 / 410	Stale endpoint (browser heeft sub verwijderd)	Auto-delete in sendOne
5xx	Tijdelijke fout push-service	Geen automatische retry in v1 — log + swallow
401 (send-route)	Verkeerd of ontbrekend Bearer-secret	Check INTERNAL_PUSH_SECRET
422 (send-route)	Ongeldige body	Zie payload-shape hierboven
503 (send-route)	INTERNAL_PUSH_SECRET niet geconfigureerd	Zet env-var

VAPID-configuratie

Genereer sleutels eenmalig:

npx web-push generate-vapid-keys

Zet in .env.local:

NEXT_PUBLIC_VAPID_PUBLIC_KEY="<public key>"
VAPID_PRIVATE_KEY="<private key>"
VAPID_SUBJECT="mailto:admin@example.com"
INTERNAL_PUSH_SECRET="<min 32 chars, openssl rand -base64 32>"

Als de VAPID-envs ontbreken, returnt sendPushToUser vroeg met een console.warn; de app crasht niet.

iOS-quirks

• Vereist iOS 16.4+ (Safari 16.4).
• De gebruiker moet de app eerst via Zet op beginscherm als PWA installeren. Push werkt niet vanuit een normale Safari-tab.
• In de EU (iOS 17.4+ na DMA) worden meldingen door Apple beperkt voor alternatieve browser-engines; test op Safari specifiek.
• isIOSSafari() + !isStandalonePWA() → PushToggle toont de installatie-banner in plaats van een toggle.

Demo-users

subscribeToPushAction controleert session.isDemo en returnt zonder schrijven. Demo-gebruikers kunnen zich dus niet aanmelden voor push.

Triggeren vanuit MCP of server-code

// Directe server-aanroep (binnen Next.js):
import { sendPushToUser } from '@/lib/push-server'
await sendPushToUser(userId, { title: 'Vraag van Claude', body: question, url: `/products/${productId}` })

// Vanuit MCP / externe service (HTTP):
await fetch(`${BASE_URL}/api/internal/push/send`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${INTERNAL_PUSH_SECRET}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId, payload: { title, body, url } }),
})
// 204 = verzonden, 503 = VAPID niet geconfigureerd

Admin testroute

curl -X POST https://<host>/api/internal/push/test-send \
  -H "Cookie: <admin session cookie>"
# Vereist ingelogde admin-sessie; stuurt push naar eigen account.