Troubleshooting install

Start with Install Doctor in the dashboard. It checks SDK, worker, scope, and a test subscription path.

HTTPS only

Browsers will not enable Push on insecure HTTP. There is no HTTP subdomain proxy. Serve the real origin on HTTPS.

Origin allowlist

The site origin in EngageNudge must match the origin in the address bar (scheme + host + port). www vs apex is a mismatch. Pairing and the SDK will fail until they match.

Service worker

Symptom	What to check
Worker 404	File not at `/en-sw.js`. Permalinks, CDN, or hosting rewrite.
Wrong scope	Worker must control `/`, not a subdirectory only.
Not controlling	Stale worker. Unregister in DevTools → Application, hard refresh, purge CDN.
GTM green SDK, red worker	Expected if `/en-sw.js` is missing. GTM cannot install it.
Worker 403, or HTML where JavaScript should be	A bot filter is challenging the request. See below.

Merge path: importScripts('/en-sw.js'); at the top of the existing root worker.

When a bot filter sits in front of the file

Cloudflare, most WAFs and several hosting platforms challenge requests that do not look like a person browsing. A challenge on /en-sw.js returns an interstitial HTML page instead of JavaScript, the worker never registers, and nothing in the dashboard says so. Visitors simply never become subscribers.

Open https://your-origin/en-sw.js in a browser. JavaScript means you are fine. HTML, a "checking your browser" page, or a 403 means the file is being challenged.

The fix is a rule that lets that one path through without a challenge. On Cloudflare: Security → WAF → Custom rules, match http.request.uri.path eq "/en-sw.js" and choose Skip. Match the exact path rather than a substring, so the exemption covers the worker and nothing else.

If you run a web app manifest for the iOS Home Screen path, give /manifest.json the same treatment.

CSP

Blocked script or worker shows up as SDK not loaded or worker HTTP error. See CSP.

Permission denied

The visitor (or you) blocked notifications. Chrome remembers that. Reset site permissions. On iOS, the site must be on the Home Screen first. See Opt-in.