Start typing to search the documentation.

↑↓to navigate·↵to open

Push

Service worker setup

Host the WRNexus Web Push service worker on your own origin — hosting rules, scope and MIME requirements, what the worker does, and the optional re-subscribe config.

The service worker is the one file you must host yourself. A service worker can only control the origin it is served from, so the browser will not let WRNexus register a worker for your domain — you copy our template to your origin and serve it there.

Get the template

Download the current template from:

https://api.wrnexus.com/push/sw.js

Save it to the root of your site and serve it at:

https://your-domain.example/wrnexus-push-sw.js

The path must match what the SDK registers. The default is /wrnexus-push-sw.js; if you host it elsewhere, set data-sw on the snippet to the same path.

Hosting requirements

Requirement Why
Same origin as your pages A worker can only control its own origin. It cannot live on a CDN at a different host.
HTTPS (or http://localhost) Service workers and the Push API require a secure context.
Content-Type: text/javascript Browsers reject a worker served with the wrong MIME type.
Reachable at the registered path Defaults to /wrnexus-push-sw.js; must match data-sw.

Scope and the Service-Worker-Allowed header

A worker’s scope (the set of pages it controls) defaults to the directory it is served from. Serving the worker at the site root (/wrnexus-push-sw.js) gives it the default scope /, which is what you want.

If you must serve it from a sub-path (e.g. /assets/wrnexus-push-sw.js) but still want it to control the whole site, the server must send:

Service-Worker-Allowed: /

and you must set data-sw-scope="/" on the snippet. Without that header the browser raises a scope error (see Troubleshooting).

What the worker does

The core behaviour needs no configuration — every tracking URL is baked into the push payload that the WRNexus send pipeline builds, so the worker just reads them out:

  • push — parses the payload, calls showNotification(title, options), and POSTs the delivered receipt to the signed deliveredUrl in the payload.
  • notificationclick — closes the notification and opens clickUrl, a signed WRNexus redirect that records the clicked event and 302s to the real destination. It reuses an existing tab on the destination when one is open.
  • pushsubscriptionchange — optional; re-subscribes silently after the browser rotates a subscription (see below).

The payload fields the worker understands: title, body, icon, image, badge, tag (falls back to campaignId), requireInteraction, clickUrl, url, deliveredUrl, campaignId, subscriptionId.

Optional: automatic re-subscribe on key rotation

Browsers occasionally rotate a push subscription, firing pushsubscriptionchange. To re-subscribe silently (so you do not lose the subscriber), fill in the WRNEXUS_PUSH_CONFIG block at the top of the worker file. Leave it blank to skip this — your subscriber will simply re-subscribe the next time they visit a page running the SDK.

var WRNEXUS_PUSH_CONFIG = {
  // Your site's publicKey — same value as data-site-id in the snippet.
  siteKey: 'SITE_KEY',
  // The WRNexus API origin.
  apiBase: 'https://api.wrnexus.com',
  // Your site's VAPID public key (Push → Settings).
  vapidPublicKey: 'BPx…',
};

On rotation the worker re-subscribes with that VAPID key and POSTs the fresh subscription to /api/push/subscriptions.

Updating the worker

The worker calls skipWaiting() and clients.claim() on install/activate, so a new version takes control as soon as the browser fetches it. The template is served with a short cache (max-age=600), so re-copying the latest sw.js periodically keeps you current. Browsers re-check a registered worker on navigation roughly every 24 hours regardless.

Next steps