Appearance
Hosting your service worker
Push notifications need a small file called a service worker (sw.js) on your website. It's what lets a visitor's browser receive and show your notifications, even when your site isn't open.
Why it has to be on your site
Browsers only accept a service worker from the same website that asks visitors to subscribe. If your site is https://example.com, the file must be at https://example.com/sw.js. That's a browser security rule, so we can't host it for you.
The service worker:
- receives notifications and shows them to your subscribers,
- opens the right page when a subscriber clicks a notification,
- keeps the subscription working when the browser renews it.
When you don't need one
If a placement has Push notifications off — it runs in-page, pop or exit ads only — there is nothing to register, so you don't have to host sw.js. The onboarding wizard's Collect push subscribers switch is where you say so, and the install check then looks for the snippet alone.
A placement that already has subscribers is different: keep sw.js on your site even after you switch collection off, because it is what delivers notifications to the subscribers you kept. See Turn subscriber collection on or off.
Set it up
Go to Placements and open the Get Code action on your placement's row. (During sign-up, the onboarding wizard shows the same instructions.)
Step 1 — copy the script snippet into your site's
<head>. It looks like this:html<script src="https://cdn.dlserve.ai/sdk/YOUR-PLACEMENT-ID.js" async></script>Step 2 — click Download sw.js (or copy its single line into a new file named
sw.js) and upload it to the top level of your website, so it opens athttps://yoursite.com/sw.js. The file is one line:jsimportScripts('https://cdn.dlserve.ai/sw/YOUR-PLACEMENT-ID.js');- Keep it at the root, not inside a folder like
/js/. - The file name must stay exactly
sw.js. - Serve it at that address directly. Browsers refuse a
sw.jsthat redirects somewhere else, even to another copy of the same file.
- Keep it at the root, not inside a folder like
Make sure your server sends it as JavaScript (
Content-Type: application/javascript). Most hosts do this automatically for.jsfiles.
The script snippet registers the service worker for you — there's no extra code to write.
Check that it works
The onboarding wizard's verification step opens your page and looks for the script snippet. Then it opens sw.js at the root of the site your page ends up on: if yoursite.com sends visitors on to www.yoursite.com, it checks https://www.yoursite.com/sw.js. Just as a visitor's browser would, it ticks sw.js hosted at your site root only when:
- the file opens at that address directly, with no redirect,
- your server sends it as JavaScript, and
- it's this placement's
sw.js, not a different service worker or another placement's file.
If the placement doesn't collect push subscribers, only the snippet is checked. If a check fails, the wizard shows why next to it. Fix that and click Re-check. Troubleshooting covers the common causes.
It updates itself
sw.js loads the latest service worker from dlserve, so when we improve it your subscribers get the change within about a day, without a new upload. You upload the file once.
Older installs host a longer file instead: a full copy that never updates. If yours does, the dashboard asks you to replace sw.js one last time. Open Get Code, download the new sw.js and replace the old file. The notice clears within a day of the new file going up.
Good to know
- HTTPS is required: service workers only run on secure (
https://) sites. - Content-Security-Policy: if your site sets a strict CSP header, it must allow dlserve's scripts and service worker — see Troubleshooting for the exact lines.
- iPhone and iPad Safari don't support web push, so no service worker runs there.