Installation

npm install @ad-shield/adblock-detector

Quick Start

ES Modules

import { detectAdblock } from "@ad-shield/adblock-detector";

const result = await detectAdblock();
if (result.isAdBlocked) {
  console.log("Ad blocker detected");
}

React

import { useEffect, useState } from "react";
import { detectAdblock } from "@ad-shield/adblock-detector";

function App() {
  const [adblockDetected, setAdblockDetected] = useState(false);

  useEffect(() => {
    detectAdblock().then((result) => {
      setAdblockDetected(result.isAdBlocked);
    });
  }, []);

  return (
    <div>
      {adblockDetected && (
        <div className="adblock-warning">
          Please disable your ad blocker to support our site.
        </div>
      )}
    </div>
  );
}

Browser (CDN)

<script src="https://cdn.jsdelivr.net/npm/@ad-shield/adblock-detector@latest/dist/index.min.js"></script>
<script>
  window.adblockDetector.detectAdblock().then((result) => {
    if (result.isAdBlocked) {
      console.log("Ad blocker detected");
    }
  });
</script>

API

detectAdblock(options?)

Returns a Promise that resolves to a detection result.

Parameters:

• options (optional): Configuration object
  • acceptableAdsTestUrls (optional): Array of exactly 2 URLs for Acceptable Ads detection. Defaults to standard test URLs.

Returns: Promise<DetectionResult>

interface DetectionOptions {
  acceptableAdsTestUrls?: readonly [string, string];
}

interface DetectionResult {
  isAdBlocked: boolean; // True if ad blocker is detected
  isAcceptableAdsBlocked: boolean; // True if acceptable ads are also blocked
}

Example:

// Basic usage
const result = await detectAdblock();
console.log(result.isAdBlocked); // true or false
console.log(result.isAcceptableAdsBlocked); // true or false

// With custom Acceptable Ads test URLs
const result = await detectAdblock({
  acceptableAdsTestUrls: [
    "https://example.com/test1.gif",
    "https://example.com/test2.gif",
  ],
});

Open Source vs. Ad-Shield

This open-source library provides accurate adblock detection, but for production-grade solutions with advanced features, consider Ad-Shield.

| Feature | Open Source | Ad-Shield | | ------------------------- | ---------------- | ------------------------------------------ | | Detection Accuracy | High | Highest (continuously updated) | | Dashboard & Analytics | ❌ Not available | ✅ Daily analytics & reporting | | Adblock Recovery | ❌ Not available | ✅ Ads work normally even with ad blockers | | Support & Updates | Community | ✅ Dedicated support & priority updates |

License

MIT © Ad-Shield