Skip to content

Integration guide ​

Getting dlserve running on your website takes about five minutes. You sign up, create a placement for your site, add one line of code and one file to the site, and check the install. After that, visitors who allow notifications become subscribers automatically.

Setting up an Android app instead? Start the same way, choose Android app (FCM) as the placement type, then follow the Android guide.

Setting up a Windows desktop app? Choose Windows app as the placement type, then follow the Windows guide.

Parking domains you own? Choose Parked domains as the placement type, then follow Parked domains.

Step 1 — Sign up ​

Create your account at https://app.dlserve.ai/auth/signup. Enter your email, a Company / publisher name and a password, then click Create account. The onboarding wizard opens straight away.

We also email you a verification link. It is valid for 24 hours. Until you click it, the wizard's button reads Verify your email to continue and you can't create a placement. If the email doesn't arrive, click Resend email in the banner at the top of the wizard. The link opens an Email verified page. Click Continue to go back to the wizard.

Step 2 — Create your placement ​

A placement is one website (or Android or Windows app) where you collect subscribers and show ads. Create one placement per site. Each placement has its own ID, snippet and sw.js, and its own subscribers and reports.

The wizard's first step asks for:

  • Placement type: Web push for a website.

  • Placement name: what you'll call it in the dashboard, for example news.example.com.

  • Website URL: your site's address including https://, for example https://news.example.com. The install check in Step 4 opens this address, so use a page that carries the snippet, such as your home page.

  • Collect push subscribers: leave it on to ask visitors to subscribe to push notifications. Turn it off only if this site will run in-page, pop or exit-intent ads alone. Then there's no sw.js to host.

  • Opt-in strategy (shown while Collect push subscribers is on): how visitors are asked to subscribe.

    Option (same label in Formats)API valueWhat the visitor sees
    Soft-ask, then browser promptgeA short message from your site first. The browser's permission prompt appears only if they accept it.
    Soft-ask + bell buttonge_uiThe soft-ask, plus a bell that stays on the page so visitors can subscribe later.
    Bell button onlyuiJust the bell. Nothing appears on its own.
    Browser prompt onlynatThe browser's permission prompt straight away.

    The soft-ask suits most sites. Once a visitor blocks the browser's own prompt, you can't ask them again. The soft-ask lets uninterested visitors say no to your message, so the browser's prompt only goes to people who want to subscribe.

  • Timezone: the clock we use for subscribers whose own timezone we don't know.

  • Sending hours: notifications can go out at any time of day unless you tick Limit sending hours.

Click Create placement.

You can change how visitors are asked at any time, without touching your code. Go to Placements, open the row menu (⋮), choose Formats and open the Push notifications tab, then Asking visitors. There, When to ask for permission lists the opt-in strategies by the codes in the table above, and Trigger sets when the prompt appears. See Subscribe prompts.

Step 3 — Install on your site ​

The wizard's Install on your site step shows two pieces. A placement that collects push subscribers needs both.

1. Paste the snippet into your site's <head>. Click Copy next to it. Your placement ID is already filled in:

html
<script src="https://cdn.dlserve.ai/sdk/YOUR-PLACEMENT-ID.js" async></script>

Add it to every page, either in your site template's <head> or through your tag manager. Because of async it never holds up your page, and in <head> it starts as early as possible:

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My site</title>
  <script src="https://cdn.dlserve.ai/sdk/YOUR-PLACEMENT-ID.js" async></script>
</head>
<body>
  <!-- your content -->
</body>
</html>

The placement ID is a long code such as 3f6c2a1e-9b4d-4e7f-8a2c-5d1e0f9b7c43. You can also find it in the ID column on Placements, with a button to copy it. Don't reuse one site's snippet on another site.

2. Host sw.js at the root of your site. Click Download sw.js and upload the file to the top level of your website, so it opens at https://yoursite.com/sw.js.

  • Keep it at the root, not in a folder such as /js/, and keep the name sw.js. The snippet looks for it at exactly that address.
  • Serve it at that address directly. Browsers refuse a sw.js that redirects somewhere else, even to another copy of the same file.
  • Your server must send it as JavaScript (Content-Type: application/javascript). Most hosts do this automatically for .js files.
  • Your site must use HTTPS. Browsers only run service workers on secure sites.

Browsers only accept a service worker from the site that asks visitors to subscribe, so we can't host this file for you. Without it, visitors can agree to notifications but never become subscribers. Hosting your service worker explains it in more detail.

If you turned Collect push subscribers off, the wizard shows the snippet alone and there's no sw.js to host.

Step 4 — Check the install ​

Click Next. The Verify your install step checks your live site from our servers:

  • Snippet on the page: we open your Website URL and look for the snippet's <script> tag, with your placement ID, in the HTML your server sends. The check doesn't run JavaScript, so it can't see a snippet that a tag manager adds after the page loads. Put the snippet straight into your page's <head> while you check. You can move it back to the tag manager afterwards.
  • sw.js hosted at your site root: we open sw.js at the root of the site your Website URL ends up on. If yoursite.com sends visitors on to www.yoursite.com, we check https://www.yoursite.com/sw.js. As in a visitor's browser, it passes 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 rather than another service worker. This row only appears when the placement collects push subscribers.

If a row shows ✗, the note beside it says what went wrong. Fix it and click Re-check. Troubleshooting covers the common causes. The check needs your site to be publicly reachable. A firewall or bot check that turns away automated requests makes it fail even when the install is fine.

Next unlocks once every row shows ✓. The check only confirms your setup. Visitors start subscribing as soon as both pieces are live on your site, whether or not you run it. To stop and come back later, click I'll finish setup later — take me to the dashboard.

The last step, You're all set, shows your Placement ID and what's next: adding in-page, pop or exit ads with Formats on Placements, and where your results and payouts show up (Reportings, Payments). Click Go to dashboard to finish.

Adding more sites ​

Each website needs its own placement. Go to Placements, click New placement, fill in the type, name and Website URL, and click Create placement. For a website, Match your site opens next and styles the soft-ask to fit your site. Click Approve & go live, or Tweak before going live to adjust it first. Then open the new placement's row menu (⋮) and choose Get Code to get the same two install pieces as in Step 3. To start from a placement you already have, choose Clone in its row menu instead.

Placements added this way skip the wizard's install check. To check one yourself, view your page's source to find the snippet, and open https://yoursite.com/sw.js in your browser. You should see JavaScript code.

What happens after install ​

Once both pieces are live, the snippet asks visitors to subscribe in the way you chose. Everyone who allows notifications becomes a subscriber of your placement. In the dashboard, Subscribers shows how many visitors saw your soft-ask (Soft-ask shown), allowed notifications (Allowed) and became subscribers (Subscribed).

dlserve then:

  1. Finds an ad for each subscriber, server to server. No ad network's address ever appears in your visitors' browser traffic.
  2. Delivers it to the subscriber's browser as a push notification. The browser shows it as coming from your site.
  3. Records deliveries, clicks and revenue for your reports.

When does the first push arrive? ​

There's no warm-up period. Every new placement starts with an hourly delivery, so a new subscriber can get a first notification within about an hour. It has to fall inside your sending hours (any time of day unless you limited them) and within your daily maximum and minimum gap. A notification only goes out when there's an ad for that subscriber, and that depends on their country and device, so early numbers can be uneven.

How visitors opt out ​

Subscribers can stop notifications at any time without contacting you. In browser settings → Notifications they find your site and change it to "Block" or "Ask". Some browsers also offer this on the notification itself.

When their browser's push service reports that the subscription has ended, dlserve stops sending to them and never messages them again. You don't need to do anything. To have a subscriber's record deleted, contact your dlserve account representative.


Next: Identify your subscribers to attach your own user IDs and tags, Troubleshooting if something isn't working, API reference for programmatic access, or FAQ for common questions.