Skip to content

Windows SDK ​

Show ads as Windows notifications from your desktop app, while the app is running. The SDK is one small DLL (dlserve.dll) that works with .NET apps and with C and C++ apps. Current version: 0.1.0.

You set the placement up in the dashboard, add a few lines to your app, test with your own PC, and go live when you're happy. If something goes wrong inside the SDK, your app keeps running. It just shows no ads.

What you need first ​

  • Windows 10 version 1809 or newer, or Windows 11. On older Windows the SDK stays quiet.
  • An x64 or x86 app. There is no ARM64 build.
  • .NET: any framework that can use .NET Standard 2.0. The samples in the zip (samples/winforms and samples/c) use .NET Framework 4.8 and plain C. They start the SDK once and call SetAdsEnabled and ShowConsent only when the user acts (a Show ads box, an Ask about ads now button), which is the pattern in steps 4 and 5 below.
  • C and C++: nothing to link. You include one header and copy one DLL.
  • A dlserve account with a verified email. See the integration guide to sign up.

1. Create the placement ​

  1. In the dashboard, go to Placements and click New placement.
  2. Set Placement type to Windows app.
  3. Fill in Placement name and App website URL: your app's website or store listing.
  4. Click Create placement.

Add to your app opens and shows your App ID. Copy it. You can open it again any time from the placement's row menu (⋮) with Get SDK.

The onboarding wizard offers Windows app too. Under Starting settings it lists the limits and consent options a new placement starts with, which you can change later in Settings. Then it shows the same Add to your app step, skips the install check, and ends on You're all set with your next steps: test, check Settings, go live.

The placement starts in Testing. Only your own test PCs get ads until you go live (step 8).

2. Add the SDK ​

.NET ​

Add the dlserve package source once, then add the package:

bash
dotnet nuget add source https://maven.dlserve.ai/nuget/index.json --name dlserve
dotnet add package Dlserve.Windows

In Visual Studio, use Tools > Options > NuGet Package Manager > Package Sources to add the same URL, then Manage NuGet Packages to install Dlserve.Windows. That also works for classic .NET Framework projects that use packages.config.

If you use a nuget.config, map the package to the dlserve source so nothing else can supply it:

xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="dlserve" value="https://maven.dlserve.ai/nuget/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="dlserve">
      <package pattern="Dlserve.Windows" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

The package copies an x64 and an x86 folder with dlserve.dll into your build output, and your app loads the one that matches the running process. An AnyCPU app with Prefer 32-bit turned on runs as x86.

C and C++ ​

  1. Download the zip from Get SDK. The newest version number is at https://maven.dlserve.ai/windows/latest.json.

  2. Check the zip against the published .sha256 file for that version, then compare the DLL with the matching line in the zip's SHA256SUMS:

    certutil -hashfile dlserve-windows-<version>.zip SHA256
    certutil -hashfile x64\dlserve.dll SHA256
  3. Add the zip's include folder to your include path and include the loader:

    c
    #include "dlserve_loader.h"
  4. Copy x64\dlserve.dll or x86\dlserve.dll next to your .exe, whichever matches your app.

There is no import library: include dlserve_loader.h and don't link anything. The loader opens the DLL itself, from your app's folder only. If the DLL is missing or blocked, the calls do nothing and your app still starts.

3. Start it ​

Start the SDK once, as early as you can. Use the App ID from Add to your app.

.NET (in Program.Main, before Application.Run, or in WPF's App.OnStartup):

csharp
using Dlserve.Windows;

DlserveSdk.Start("YOUR-APP-ID");

C and C++:

c
dls_start("YOUR-APP-ID", NULL);

Stop it when your app exits: DlserveSdk.Shutdown(); in .NET, dls_shutdown(3000); in C.

If dlserve.dll is missing or blocked, every call does nothing and your app keeps running. DlserveSdk.IsAvailable (dls_is_available() in C) tells you which it is.

4. Add an ads on/off setting ​

Your app must have its own setting that turns ads on and off. A Show ads check box in your settings window is enough. Wire it like this:

  • When your settings window opens, set the check box from IsAdsEnabled (dls_is_ads_enabled() in C).
  • Call SetAdsEnabled (dls_set_ads_enabled in C) only when the user changes the box. Never call it at startup. Otherwise you would turn ads back on, or ask again, every time the app opens.
  • IsAdsEnabled can't tell "never asked" from "said No". Both read as off.

What the call does:

  • Turning ads on asks the person first where your placement asks people. Where it doesn't, ads start quietly.
  • Turning ads off stops ads, removes any ad still on screen and stays off, also after restarts and app updates. The SDK never turns ads back on by itself.

.NET (WinForms):

csharp
using System.Windows.Forms;
using Dlserve.Windows;

public sealed class SettingsForm : Form
{
    public SettingsForm()
    {
        var showAds = new CheckBox { Text = "Show ads", AutoSize = true, Left = 16, Top = 16 };

        // Read the current state first, then listen for the user's changes.
        showAds.Checked = DlserveSdk.IsAdsEnabled;
        showAds.CheckedChanged += (sender, args) => DlserveSdk.SetAdsEnabled(showAds.Checked);

        Controls.Add(showAds);
    }
}

C (Win32):

c
#include <windows.h>
#include "dlserve_loader.h"

/* When your settings window opens: show the SDK's current state. */
void load_settings(HWND show_ads_box) {
    SendMessage(show_ads_box, BM_SETCHECK,
                dls_is_ads_enabled() ? BST_CHECKED : BST_UNCHECKED, 0);
}

/* Only when the user clicks the check box. */
void on_show_ads_clicked(HWND show_ads_box) {
    int on = SendMessage(show_ads_box, BM_GETCHECK, 0, 0) == BST_CHECKED;
    dls_set_ads_enabled(on);
}

People can also turn off notifications for your app in Windows settings. That stops the ads too, but it mutes your app's own notifications as well, because Windows has one switch per app. Your ads setting is the better way to opt out.

5. Asking users ​

Where and how people are asked is set in the dashboard under Consent mode and When to ask. See Windows placement settings. What this means for your code:

  • After N minutes in the app (the default for new placements, with N = 5): the SDK asks by itself, N minutes after each time your app starts. You don't need to call anything.
  • Only when my app calls ShowConsent: you choose the moment. Call ShowConsent once, for example after your first-run screen, and save your own "asked" flag so you don't call it again. Turning your Show ads box on also asks. Until one of those happens, nobody who would see the dialog or the notice gets ads. With Ask everyone before showing ads, that is everyone, and with Show a one-time notice outside dlserve's consent list, it is everyone the dialog or the notice would apply to. If you won't add the call, keep After N minutes in the app. Placements created before this default keep the setting they had. One exception: when someone who already gets ads now needs the notice, or dlserve's server asks for it, the SDK shows the notice by itself when the app starts.
csharp
DlserveSdk.ShowConsent(this.Handle);   // WinForms: pass your window handle so the dialog opens on top of it
// WPF: DlserveSdk.ShowConsent(new System.Windows.Interop.WindowInteropHelper(this).Handle);
c
dls_show_consent(main_window);         /* C: pass your window handle, or NULL for none */

ShowConsent shows the question right away, ignoring the After N minutes in the app wait. It asks again even after someone said No, so don't call it on every launch. If you make Consent mode stricter later, call it again so people get the new question. Where your placement doesn't need to ask, it does nothing.

6. Test ​

While the placement is in Testing, every PC that runs your app becomes a test device. You can have at most 10. A build with no Installed apps entry in Windows (for example one you run from your build folder) is always a test device.

  1. Run your app on a test PC, with ads on and notifications on for the app. A PC becomes a test device only after it registers. If the SDK asks on that PC (see Asking users), answer Allow or OK first, by calling ShowConsent or turning your Show ads box on.
  2. In the dashboard, open the placement's row menu (⋮) and choose Send test ad.
  3. Within a minute or two, a notification titled Test ad from Dlserve appears.

If the dashboard says "No test devices yet", no PC has registered: run the app, answer the question if there is one, and send again. The app has to be running, ads on, Windows notifications on for it, and the PC not in Do Not Disturb or full screen. A test ad that misses its moment is not sent again. Click Send test ad once more. Test ads never earn money.

Logging ​

The SDK is quiet by default and shows warnings only. To see what it is doing, set a log handler before you start and ask for info:

csharp
DlserveSdk.SetLogHandler((level, message) => System.Diagnostics.Debug.WriteLine($"[dlserve {level}] {message}"));
DlserveSdk.Start("YOUR-APP-ID", "{\"logLevel\":\"info\"}");
c
static void DLS_CALL on_log(int level, const char* message, void* user) {
    char prefix[32];
    (void)user;
    wsprintfA(prefix, "[dlserve %d] ", level);
    OutputDebugStringA(prefix);
    OutputDebugStringA(message);
    OutputDebugStringA("\n");
}

/* ... at startup ... */
dls_set_log_sink(on_log, NULL);
dls_start("YOUR-APP-ID", "{\"logLevel\":\"info\"}");

Log lines never contain tokens, install IDs, addresses or ad text. If a test ad doesn't show up, the log usually says why. Set logLevel in the start options and the early lines (child-directed app: ads stay off, dormant start: ads were turned off earlier) appear too. GetState() also reports dormantReason and adsEnabled. See Troubleshooting.

7. Package, install and sign ​

  • Ship the DLL that matches your app. x64 app, x64 DLL. x86 app, x86 DLL. Don't rename it or pack it into another file.
  • Sign it yourself. dlserve.dll is not signed. Sign it with your own certificate in the same step that signs your .exe. Unsigned, it can be blocked on some Windows 11 PCs (Smart App Control). Your app then runs, without ads.
  • Create an Installed apps entry. Your installer must register the app so it appears under Windows Installed apps, with InstallLocation (or DisplayIcon or UninstallString) pointing at the folder of your .exe. The SDK uses it to know the app is installed, and takes the app's name from it. Inno Setup and NSIS installers that write an uninstaller into the app folder work as they are. A WiX or MSI installer must set ARPINSTALLLOCATION, because its default UninstallString (MsiExec.exe /X{...}) doesn't point at your folder. An MSIX package you sideload needs no entry. Before you release, install with your real installer, turn on info logging and confirm the registered (...) line does not say test device.
  • Don't start the app as administrator from the installer. When the app runs elevated, the SDK stays quiet. Let the installer start it as the signed-in user.
  • Don't ship to the Microsoft Store or winget. Store policy doesn't allow these ads, and winget isn't supported yet. As a safety net, a Store-signed MSIX package stays quiet, but an EXE or MSI listed in the Store does not. That is not permission to ship there.

Uninstall ​

Call dls_uninstall_cleanup("YOUR-APP-ID") from your uninstaller, running as the user. It is not part of the .NET package, so call it from native uninstaller code. Call it only on a real uninstall, never on an update.

  • Run it from an .exe in your app's folder, with dlserve.dll beside it. From anywhere else it returns -5 and does nothing. Check for 0.
  • Where the DLL sits depends on your app. C/C++: dlserve.dll is next to your .exe (step 4 above), so the helper .exe sits there too. .NET: the package puts the DLL in x64\ and x86\, so put the helper .exe in the folder that matches its bitness (x64\ for a 64-bit helper) and ship it there.
  • It is refused when the uninstaller runs as administrator, even though the call still returns 0. It works for per-user installs and for uninstall steps that run unelevated.
  • Inno Setup: a direct cdecl import from the DLL also works, if the DLL's bitness matches Inno's. Inno Setup 6 uninstallers are 32-bit, so import the x86 DLL. Inno Setup 7 with SetupArchitecture=x64 can import the x64 DLL. Mark the import uninstallonly and call UnloadDLL before the uninstaller removes your files.

It removes what the app left on the PC and tells dlserve the install is gone. If you don't call it, the install stays active on dlserve's side, so say so in your privacy policy, and these can stay behind: the folder %LOCALAPPDATA%\dlserve\<App ID> and the registry key HKCU\Software\Classes\AppUserModelId\dlserve.<App ID>.

8. Go live ​

  1. Open the placement's row menu (⋮) and choose Go live.
  2. Confirm. The dialog says which installs real ads will run for, set by Countries in Settings.

Before you release your app:

  • Host your privacy policy and set Privacy policy URL (optional).
  • Check Consent mode, When to ask and Countries in Settings.
  • Read Requirements and risks.

Go live before you release your app. Good to know:

  • PCs that were test devices stay test devices after you go live. They change when they register again (up to 30 days) or when ads are turned off and on in the app.
  • To keep testing after you go live, use a build with no Installed apps entry on a PC in your Countries: on a Live placement, a PC outside them is refused, test device or not. Or Clone the placement and keep the copy in Testing. The copy has its own App ID, so start your test build with it (from the copy's Get SDK).
  • Back to testing in the row menu puts the placement back to test devices only.
  • The first real ad waits 60 minutes after a computer registers.

What your users see ​

  • A Windows notification with your app's name and icon, the ad's title and text, sometimes a picture, and the label Ad.
  • No buttons and no sound. It goes away after about 25 seconds.
  • A click opens the ad in the person's default browser.
  • It only appears while your app is running. It is held back in full screen, during presentations, on the locked screen and in the first hour after a new Windows user account first signs in, and never shown under Do Not Disturb or with notifications off for your app.
  • At least 10 minutes between two ads, and never more than your Max ads per user per day.
  • One copy of your app per Windows session fetches ads. A second copy stays quiet.

SDK reference ​

.NET ​

Namespace Dlserve.Windows, static class DlserveSdk.

MemberWhat it does
Start(string appId) / Start(string appId, string optionsJson)Starts the SDK. Returns a status code.
ShowConsent(IntPtr ownerHwnd = default)Shows the question now where your placement asks.
SetAdsEnabled(bool enabled)Your ads setting. Returns a status code.
IsAdsEnabledTrue while ads are on.
GetState()The state as a JSON string, or an empty string when unavailable.
Shutdown(int timeoutMs = 3000)Stops the SDK. Call it at exit.
SetLogHandler(Action<int, string>)Receives log lines. Level 1 is error up to 4 for debug. null removes it.
IsAvailableTrue when dlserve.dll was found and works.
VersionThe DLL's version, or an empty string.

C and C++ ​

CallWhat it does
dls_start(app_id, options_json)Starts the SDK. options_json may be NULL.
dls_show_consent(owner_hwnd)Shows the question now where your placement asks.
dls_set_ads_enabled(enabled)Your ads setting.
dls_is_ads_enabled()1 while ads are on, else 0.
dls_is_available()1 when the SDK works, else 0.
dls_get_state(buf, cap, &needed)Writes the state JSON.
dls_shutdown(timeout_ms)Stops the SDK. Call it at exit.
dls_uninstall_cleanup(app_id)Removes what the app left behind. Works without dls_start.
dls_set_log_sink(sink, user)Receives log lines. NULL removes it.
dls_last_error(buf, len)The last error message on this thread.
dls_version() / dls_abi_version()The SDK version and the interface revision.

Start options ​

A JSON object. Only these keys are accepted. Anything else is an invalid argument.

KeyValueWhat it does
logLevel"off", "error", "warn", "info" or "debug"How much the log handler hears. Default "warn".
childDirectedtrue or falsetrue keeps the SDK off. See Requirements and risks.
aumidtextYour app's own Windows notification identity, if it has one.

State ​

GetState() and dls_get_state return JSON like this:

json
{"abiVersion":1,"version":"0.1.0","started":true,"adsEnabled":true,"inert":false}
FieldMeaning
abiVersionThe interface revision of the DLL.
versionThe SDK version.
startedtrue after a successful start.
adsEnabledtrue while ads are on.
inerttrue when the SDK can't do anything.
dormantReasonOnly present when the SDK started but stays quiet on this PC.

dormantReason is one of:

ValueWhy the SDK is quiet
elevatedThe app runs as administrator.
store_packageThe app is a Microsoft Store package.
old_osWindows is older than 10 version 1809.
child_directedYour app set childDirected.
another_instanceAnother copy of your app in this Windows session is fetching ads.

Return codes ​

Code.NET nameMeaning
0DlserveStatus.OkSuccess.
-1DlserveStatus.InvalidArgumentAn empty or malformed argument.
-2DlserveStatus.NotStartedStart hasn't succeeded yet.
-3DlserveStatus.BufferTooSmallThe buffer can't hold the result.
-4DlserveStatus.InternalAn error was caught. The SDK is quiet from now on.
-5DlserveStatus.Unavailabledlserve.dll is missing, blocked or too old. Every call does nothing.

dls_login, dls_logout, dls_set_tags and dls_set_event_callback exist, but this version accepts them and ignores them. The .NET package doesn't offer them.

Troubleshooting ​

No ads, or no test ad? See Troubleshooting: Windows apps.


Next: Windows placement settings to set limits, consent and countries, Requirements and risks before you ship, or Troubleshooting if something isn't working.