Start typing to search the documentation.

↑↓to navigate·↵to open

Push

Web Push overview

Browser push notifications for your website — how WRNexus sites, the on-page SDK, customer-hosted service worker, VAPID keys, subscribers, campaigns, and first-party tracking fit together.

WRNexus Web Push turns any website into a notification channel: visitors opt in from a browser permission prompt, and you reach them with a campaign even after they have left your site. It works in every browser that implements the W3C Push API and Notifications API — Chrome, Edge, Firefox, Opera, Samsung Internet, and Safari 16.4+.

How it fits together

A site is a web property registered for push. Creating a site provisions a dedicated VAPID keypair and a non-secret site key (publicKey) that identifies it everywhere.

            your website                         WRNexus
  ┌──────────────────────────────┐    ┌──────────────────────────────┐
  │  <script …/push/sdk.js        │    │  GET /push/config?siteKey=…   │
  │        data-site-id="SITE">   │───▶│    → VAPID public key + apiBase│
  │                               │    │                               │
  │  WRNexusPush.prompt()         │    │  POST /api/push/subscriptions │
  │   → browser permission prompt │───▶│    → stores the subscription   │
  │   → PushSubscription          │    │                               │
  │                               │    │  ── campaign send ──▶ browser  │
  │  /wrnexus-push-sw.js (yours)  │◀───┤  push payload (signed track    │
  │   → showNotification()        │    │    URLs inside)                │
  │   → notificationclick         │───▶│  GET /api/push/track/click/…   │
  └──────────────────────────────┘    └──────────────────────────────┘

The moving parts:

Piece Where it lives Purpose
Site WRNexus (Push dashboard) A registered web property. Owns a VAPID keypair, a site key, frequency caps, and quiet hours.
SDK loader (/push/sdk.js) Served by WRNexus, <script>-loaded on your page Reads data-site-id, fetches config, registers the worker, subscribes, POSTs the subscription.
Service worker (/wrnexus-push-sw.js) Hosted on your own origin Receives pushes, shows the notification, fires click/delivery tracking.
Subscriber WRNexus A browser’s PushSubscription (endpoint + p256dh/auth keys), scoped to your workspace.
Campaign WRNexus A notification (title, body, icon, target URL) sent to a site’s active subscribers, optionally filtered by a segment or topic.
Tracking WRNexus public endpoints First-party delivered / clicked / opened / unsubscribed events recorded against each subscription.

Why the service worker must be on your origin

A service worker can only control the origin it is served from. The browser will not let wrnexus.com register a worker for your-domain.example, so the worker file is a template you copy to the root of your own site and serve over HTTPS. Everything else (the SDK loader, config, subscription writes, and tracking) is hosted by WRNexus and reached cross-origin. See the Service worker setup guide for the hosting requirements.

VAPID keys

VAPID (Voluntary Application Server Identification) is how a push service authenticates the sender. Each site gets its own P-256 keypair when it is created:

  • The public key (an uncompressed P-256 point, base64url-encoded) is the browser’s applicationServerKey when it subscribes. It is served to the SDK by GET /push/config and shown under Push → Settings. It is safe to expose.
  • The private key never leaves WRNexus — it signs the push request so the push service accepts it.

You do not generate or rotate these by hand; creating a site provisions them and the active key is what the SDK and send pipeline use.

Opt-in is always user-initiated

The SDK never requests notification permission on page load. Loading the snippet only warms the config and pre-registers the worker (and refreshes the record for a browser that is already subscribed). The browser permission prompt appears only when your site calls WRNexusPush.prompt() from a real user gesture — a click on an “Enable notifications” control. This keeps you compliant with Chrome’s and Firefox’s abusive-notification heuristics, which penalise sites that prompt without interaction.

Next steps