Troubleshooting Guide

Quick solutions to common DL API SDK problems. Problem → Solution format.

AdInspector Bookmarklet

Quick visual debugging with AdInspector JavaScript bookmarklet.

Install AdInspector

Just go to http://csr.onet.pl/adinspector/ and click the “Install AdInspector” button — that’s all.
The bookmarklet will be automatically added to your browser’s bookmarks bar.

Highlight ad slots (Overlay)

Open any page with ads and click the AdInspector bookmarklet.
The AdInspector toolbar appears at the bottom — select Overlay.
All detected ad slots on the page will be highlighted. Each overlay shows:
- Slot name (e.g., top)
- Ad / line item IDs with quick links to details
- Hints like “Click to view Line Item / Creative” or “Turn on slot view overlay”

📘
Click a highlighted area to open its details. Click Overlay again to turn the highlights off.

Quick Problem Solver

Symptom	Likely Cause	Fix
No ads showing	No matching campaign	Use `target: "TEST/AREATEST"` to verify SDK works
"dlApi is not defined"	Script not loaded yet	Use `dlApi.cmd.push()` wrapper for all SDK calls
Ads showing then disappearing	Container DOM modified	Don't touch slot element after `defineSlot()`
Console error: "tid required"	Missing tenant ID	Add `tid: YOUR_TENANT_ID` to config
Slot collapses immediately	No fill from ad server	Check targeting matches campaign setup
Click tracking not working	Custom rendering broken	Preserve `ad.meta.adclick` URL prefix
Ads not lazy loading	Config wrong	Set `lazy: 1` in global config
Events not firing	Timing issue	Wrap code in `dlApi.cmd.push(function(dlApi) {...})`
Multiple ads in same slot	Duplicate `fetch()` calls	Define all slots, then call `fetch()` once
Ads load on every scroll	No lazy load guard	Use `lazy: 1` or check `shouldCallSlotNow()`
GDPR consent issues	CMP not ready	Use `getConsentsData()` callback pattern
Test ads work, real don't	Targeting mismatch	Verify `target` and `keyvalues` match campaign

Diagnostic Script

Run this to diagnose most common issues:

// Complete diagnostic check
dlApi.cmd.push(function(dlApi) {
  console.group("🔍 DL API SDK Diagnostics");

  // 1. SDK loaded and version
  console.log("✓ SDK Version:", dlApi.VERSION || "Unknown");
  console.log("✓ SDK loaded:", !!window.dlApi);

  // 2. Configuration check
  console.group("⚙️  Configuration");
  console.log("Config object:", dlApi.config);
  console.log("Target:", dlApi.config.target || "⚠️ MISSING");
  console.log("Tenant ID:", dlApi.config.tid || "⚠️ MISSING (may cause issues)");
  console.log("Autoslot:", dlApi.config.autoslot);
  console.log("Lazy loading:", dlApi.config.lazy);
  console.groupEnd();

  // 3. Slots check
  console.group("📦 Slots");
  console.log("Defined slots:", Object.keys(dlApi.slots || {}).length);
  if (dlApi.slots) {
    Object.keys(dlApi.slots).forEach(function(key) {
      var slot = dlApi.slots[key];
      console.log(" -", slot.name, "→", slot.div);
    });
  }

  // Check for data-slot elements
  var dataSlots = document.querySelectorAll('[data-slot]');
  console.log("Found [data-slot] elements:", dataSlots.length);
  dataSlots.forEach(function(el) {
    console.log(" -", el.getAttribute('data-slot'), "→", el.id || "(no id)");
  });
  console.groupEnd();

  // 4. Network check
  console.group("🌐 Network");
  console.log("Check Network tab for:");
  console.log(" - Requests to: csr.onet.pl");
  console.log(" - Response status: 200 OK");
  console.log(" - Response contains ads data");
  console.groupEnd();

  // 5. Event monitoring
  console.group("📡 Events (monitoring)");
  dlApi.on("showAds", function() {
    console.log("✓ Event: showAds");
  });
  dlApi.on("afterDisplay", function(event, ad) {
    console.log("✓ Event: afterDisplay →", ad.div);
  });
  dlApi.on("empty", function(event, slot) {
    console.warn("⚠️  Event: empty →", slot.name);
  });
  dlApi.on("error", function(err) {
    console.error("✗ Event: error →", err);
  });
  console.log("Event listeners attached");
  console.groupEnd();

  // 6. Browser environment
  console.group("🌍 Environment");
  console.log("User Agent:", navigator.userAgent);
  console.log("Cookies enabled:", navigator.cookieEnabled);
  console.log("Third-party blocked:", !navigator.cookieEnabled || "check manually");
  console.log("Page URL:", window.location.href);
  console.log("Referrer:", document.referrer || "(none)");
  console.groupEnd();

  console.groupEnd();
  console.log("📋 Copy diagnostics above and share with support if needed");
});

To run: Paste into browser console or add to your page temporarily.

Common Mistakes

1. Modifying Slot After Creation

❌ WRONG:

// Create slot
dlApi.cmd.push(function(dlApi) {
  dlApi.defineSlot("top", "ad-top");
  dlApi.fetch();
});

// Later... BAD!
document.getElementById('ad-top').innerHTML = "Loading...";

✅ RIGHT:

// Create slot and leave it alone
dlApi.cmd.push(function(dlApi) {
  dlApi.defineSlot("top", "ad-top");
  dlApi.fetch();
});

// Use events instead
dlApi.cmd.push(function(dlApi) {
  dlApi.on("beforeDisplay", function(event, ad) {
    console.log("Ad is loading...");
  });
});

2. Multiple Fetch Calls

❌ WRONG:

dlApi.cmd.push(function(dlApi) {
  dlApi.defineSlot("top", "ad-top");
  dlApi.fetch();  // First request

  dlApi.defineSlot("sidebar", "ad-sidebar");
  dlApi.fetch();  // Second request (inefficient!)
});

✅ RIGHT:

dlApi.cmd.push(function(dlApi) {
  // Define all slots first
  dlApi.defineSlot("top", "ad-top");
  dlApi.defineSlot("sidebar", "ad-sidebar");

  // Single fetch for all
  dlApi.fetch();
});

3. Not Using Command Queue

❌ WRONG:

// SDK might not be ready yet
dlApi.defineSlot("top", "ad-top");  // May fail!

✅ RIGHT:

// Always use command queue
dlApi.cmd.push(function(dlApi) {
  dlApi.defineSlot("top", "ad-top");  // Safe
});

4. Forgetting Tracking in Custom Templates

❌ WRONG:

dlApi.registerTemplate({
  tplCode: "1746213/Custom",
  renderAd: function(ad) {
    var link = document.createElement('a');
    link.href = ad.fields.url;  // Missing click tracker!
    // Missing impression pixel!
  }
});

✅ RIGHT:

dlApi.registerTemplate({
  tplCode: "1746213/Custom",
  renderAd: function(ad) {
    // Track impression
    if (ad.meta.impression) {
      new Image().src = ad.meta.impression;
    }

    // Track clicks (preserve prefix)
    var link = document.createElement('a');
    link.href = ad.meta.adclick + ad.fields.url;
  }
});

5. Infinite Scroll Without Unique IDs

❌ WRONG:

function loadMore() {
  dlApi.cmd.push(function(dlApi) {
    // Same ID every time!
    dlApi.defineSlot("infeed", "ad-infeed");
    dlApi.fetch();
  });
}

✅ RIGHT:

var adCount = 0;

function loadMore() {
  adCount++;

  dlApi.cmd.push(function(dlApi) {
    // Unique ID each time
    var divId = "ad-infeed-" + adCount;
    var div = document.createElement("div");
    div.id = divId;
    document.querySelector(".feed").appendChild(div);

    dlApi.defineSlot("infeed", divId, {pos: adCount});
    dlApi.fetch();
  });
}

6. Lazy Loading Config Error

❌ WRONG:

dlApi = {
  target: "SITE/AREA",
  lazyLoad: true  // Wrong property name!
};

✅ RIGHT:

dlApi = {
  target: "SITE/AREA",
  lazy: 1,              // Correct
  lazyPercentage: 150   // Optional: load 1.5 viewports ahead
};

7. SPA Without Cleanup

❌ WRONG:

// React/Vue route change
function navigateToNewPage() {
  // Old ads still in memory!
  dlApi.cmd.push(function(dlApi) {
    dlApi.defineSlot("top", "ad-top");
    dlApi.fetch();
  });
}

✅ RIGHT:

// React/Vue route change
function navigateToNewPage() {
  dlApi.cmd.push(function(dlApi) {
    // Clean old slots first
    dlApi.destroySlots();

    // Update context
    dlApi.changeView({
      target: "SITE/NEWPAGE"
    });

    // Create new slots
    dlApi.defineSlot("top", "ad-top");
    dlApi.fetch();
  });
}

Environment-Specific Issues

Issue: Ads work locally but not in production

Checklist:

Different target value between environments?
Different tid (tenant ID)?
HTTPS vs HTTP (use HTTPS)?
CORS/CSP headers blocking requests?
Ad blocker on production domain?

Debug:

dlApi.cmd.push(function(dlApi) {
  console.log("Environment:", {
    target: dlApi.config.target,
    tid: dlApi.config.tid,
    protocol: window.location.protocol,
    domain: window.location.hostname
  });
});

Issue: Ads work on desktop but not mobile

Checklist:

Mobile-specific ad blocker?
Different screen size → no matching creatives?
Viewport too small for ad sizes?
Mobile browser blocking third-party cookies?

Debug:

dlApi.cmd.push(function(dlApi) {
  console.log("Mobile check:", {
    isMobile: dlApi.isMobile(),
    screenWidth: window.innerWidth,
    screenHeight: window.innerHeight,
    userAgent: navigator.userAgent
  });
});

Issue: GDPR consent blocking ads

Checklist:

User declined ad consent?
CMP not loaded yet?
Consent string invalid?

Debug:

dlApi.cmd.push(function(dlApi) {
  dlApi.getConsentsData(dlApi, function(consents) {
    console.log("GDPR consents:", consents);
    console.log("Has vendor consent:", consents.vendor);
    console.log("Has purpose consent:", consents.purpose);
  });
});

Testing Checklist

Before deploying, verify:

Basic Integration

SDK script loads (check Network tab)
No console errors
Test ads show with TEST/AREATEST
Real ads show with production config
Ads visible in correct slots
Ads don't break page layout

Tracking

Impressions tracked (check Network tab for pixel requests)
Clicks tracked (URLs have tracking prefix)
Viewability events fire (use event listeners)

Performance

Lazy loading works (ads load near viewport)
No duplicate ad requests
Page load not blocked by ads
Core Web Vitals not degraded

Edge Cases

No ads available (slot collapses gracefully)
Ad blocker enabled (page still works)
Slow network (ads timeout gracefully)
Small screens (responsive ads render)

GDPR/Privacy

Consent banner shows (if required)
Ads respect consent choices
Non-personalized ads when consent declined
Cookie policy accurate

Still Stuck?

1. Enable Full Debug Mode

// Add to page temporarily
dlApi = {
  target: "SITE/AREA",
  debug: 1,    // Enable debug logging
  async: 1
};

Then add to URL:

?dl_debug=1

2. Check Network Tab

Look for:

✓ Request to csr.onet.pl → Status 200
✓ Response contains ads array
✗ Any 404, 500 errors
✗ CORS errors
✗ Blocked requests

3. Test with Minimal Example

Create a clean test page:

<!DOCTYPE html>
<html>
<head>
  <script>
    dlApi = {
      target: "TEST/AREATEST",
      autoslot: 1,
      async: 1,
      debug: 1
    };
  </script>
  <script src="//lib.onet.pl/s.csr/build/dlApi/dl.boot.min.js" async></script>
</head>
<body>
  <h1>DL API SDK Test</h1>
  <div data-slot="top"></div>

  <script>
    dlApi.cmd.push(function(dlApi) {
      console.log("SDK ready:", dlApi);
      console.log("Config:", dlApi.config);
    });
  </script>
</body>
</html>

If this works, problem is in your integration code. If this fails, contact support with browser console output.

4. Contact Support

Include in your message:

Browser console output (copy full diagnostic script results)
Network tab screenshot (showing CSR requests)
Your configuration code
Expected vs actual behavior
Browser and device info

Email: [support email here] Documentation: [docs URL here]

SDK Version Issues

Check Your Version

dlApi.cmd.push(function(dlApi) {
  console.log("DL API SDK Version:", dlApi.VERSION);
});

Update SDK

Always use latest version:

<script src="//lib.onet.pl/s.csr/build/dlApi/dl.boot.min.js" async></script>

Don't cache or host SDK locally - you'll miss critical updates.

Related Resources

SDK Recipes - Common integration patterns
Advanced Recipes - Debug, native ads, custom rendering
DL API SDK Reference - Complete API documentation