Push Notifications

Soryk uses push notifications () end-to-end. Notifications work natively in:

Desktop browsers — Chrome, Edge, Firefox, Safari (16+).
Android Chrome and Chrome-derived browsers.
iOS Safari, but only when the agent app is added to the home screen as a app and only on iOS 16.4 or newer.
Native iOS / Android apps — same push notifications channel under the hood, no separate APNs/FCM setup needed.

Overview

Browsers maintain a permanent subscription against your server. Soryk stores serialized subscriptions in Upstash, keyed by (shop, agent). When a triggering event happens, the server posts an encrypted message to the push endpoint with -signed headers. The browser wakes the, which displays the notification — even if the app isn't open.

secure push tech setup

You need three env vars:

VAPID_PUBLIC_KEY="BJL...your-public-key..."
VAPID_PRIVATE_KEY="abc...your-private-key..."
VAPID_SUBJECT="mailto:support@yourbrand.com"

Generate the keys

npx web-push generate-vapid-keys

Copy the public key into VAPID_PUBLIC_KEY and the private into VAPID_PRIVATE_KEY. Set VAPID_SUBJECT to a mailto: URL — push providers use it to contact you in case of abuse reports.

Don't rotate secure push tech casually. Subscriptions are tied to the public key. Rotating means every existing subscription becomes invalid and every agent has to re-subscribe.

Subscription flow

Agent opens the app.
Service worker (/sw.js) registers on first load.
The PushRegistrar component checks Notification.permission:
- granted → auto-creates a subscription via the public key endpoint.
- default → does nothing yet. The toggle in Settings shows "Enable".
- denied → toggle shows disabled state with link to browser instructions.
Agent opens Settings → Notifications and taps the toggle. Browser prompts for permission. On grant → subscription is created and POSTed to /api/agent/push/subscribe.
The serialized subscription is stored in Upstash set soryk:push:<shop>:<agent>.

Supported triggers

Event	Recipient	Notes
Public quote accepted	Originating agent	Fires when a customer clicks Accept on a public quote link.
Public quote rejected	Originating agent	Fires when a customer clicks Reject.
Discount approved	Requesting agent	When admin approves a pending discount, the agent gets a push.
Discount rejected	Requesting agent	Same, on rejection.
Refund commission alert	Admin (browser session)	Optional — surface refund alerts to active admin sessions in real time.

Dead subscriptions (HTTP 404 / 410 from the push provider) are pruned automatically.

Disabling

From the agent's Settings → Notifications, toggle off. The subscription is removed from Upstash and the browser-side endpoint is unsubscribed.

To disable globally for all agents, unset the env vars. The send function becomes a no-op and the toggle hides itself in the UI (it checks the /api/agent/push/public-key response — empty string means no push).

iOS app caveat

iOS Safari requires the home-screen install. push notifications on iOS only works when the user has added the app to the home screen via the Share menu and is using iOS 16.4 or newer. In a regular Safari tab, push will not register — there's nothing we can do about that until Apple changes the platform.

For users on the native iOS app from the App Store, this isn't an issue — the app uses the same push notifications channel transparently.

iOS install instructions for your agents

Open the app URL in Safari (must be Safari, not Chrome on iOS).
Tap the Share button (square with arrow).
Scroll and tap "Add to Home Screen".
Open the app from the home screen icon (not from Safari).
Sign in. Open Settings → Notifications. Tap the toggle. Grant permission.

Troubleshooting

Toggle doesn't appear in Settings — env vars not configured. Set them and redeploy.
"Enable" toggle but nothing happens on tap — browser blocked permission previously. Open browser site settings and reset notifications for the Soryk domain.
Notifications work in Chrome but not iOS — agent is on iOS < 16.4 or hasn't installed as app. See above.
No push fires on quote accept — check that the agent has Notifications → ON in their settings and the subscription appears in Upstash. If subscription exists but no push: check private key matches public key.
Push fires but never appears — may be old. Force-refresh the app twice; the SW updates with cache version soryk-shell-v3 on next load.

Was this helpful?

Edit this page on GitHub