# Troubleshooting Guide

Quick solutions to common DL API SDK problems

# 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/](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)

1. Open any page with ads and click the **AdInspector** bookmarklet.
2. The AdInspector toolbar appears at the bottom — select **Overlay**.
3. 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”

<Callout icon="📘" theme="info">
  Click a highlighted area to open its details. Click **Overlay** again to turn the highlights off.
</Callout>

<Image border={false} src="https://files.readme.io/5cc117a7365e653db893240f5b5516c37939bb8301d69eb28b7b893b16bd9c77-image.png" />

<br />

***

## 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:

```javascript
// 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:**

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

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

**✅ RIGHT:**

```javascript
// 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:**

```javascript
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:**

```javascript
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:**

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

**✅ RIGHT:**

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

***

### 4. Forgetting Tracking in Custom Templates

**❌ WRONG:**

```javascript
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:**

```javascript
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:**

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

**✅ RIGHT:**

```javascript
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:**

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

**✅ RIGHT:**

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

***

### 7. SPA Without Cleanup

**❌ WRONG:**

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

**✅ RIGHT:**

```javascript
// 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:**

```javascript
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:**

```javascript
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:**

```javascript
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

```javascript
// 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:

```html
<!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

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

### Update SDK

Always use latest version:

```html
<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](./sdk-recipes.md) - Common integration patterns
* [Advanced Recipes](./sdk-recipes-advanced.md) - Debug, native ads, custom rendering
* [DL API SDK Reference](/reference/dl-api-sdk.json) - Complete API documentation