npm package: @pvitor/adblock-detector
Description: adblock detectector
Latest version: 1.0.0

# Multi Adblock Detector

This project is a fork of [multi-adblock-detect](https://github.com/arjun-menon/multi-adblock-detect), modified for compatibility with older React versions (^16) with changes to Promise returns and improvements to adblock detection techniques.

## 🚀 Features

- **React 16+ compatibility** - Works with legacy React projects
- **Promise-based API** - Modern async/await support with consistent Promise returns
- **Multiple detection methods** - 6 different adblock detection techniques
- **Improved reliability** - Enhanced timeout handling and better error management
- **TypeScript support** - Full TypeScript definitions included

## 📦 Installation

```bash
npm install @pvitor/adblock-detector
```

## 🔧 Usage

```js
import {
    detectAdBlockFetchOrXhrAdsByGoogle,
    detectAdBlockFetchDoubleClick,
    detectAdBlockScriptAdsByGoogle,
    detectAdBlockBaitElementOrXhrGoogle,
    detectAdBlockScriptAdsJs,
    detectAdBlockScriptSailthruJs
} from "@pvitor/adblock-detector";

 async function detectMultiAdBlockMethods() {

  try {

    const [
      HasDetectAdBlockFetchOrXhrAdsByGoogle,
      HasDetectAdBlockFetchDoubleClick,
      HasDetectAdBlockScriptAdsByGoogle,
      HasDetectAdBlockBaitElementOrXhrGoogle,
      HasDetectAdBlockScriptAdsJs,
      HasDetectAdBlockScriptSailthruJs
    ] = await Promise.all([
      detectAdBlockFetchOrXhrAdsByGoogle('/pagead/js/adsbygoogle.js'),
      detectAdBlockFetchDoubleClick(),
      detectAdBlockScriptAdsByGoogle(),
      detectAdBlockBaitElementOrXhrGoogle('/ads/pagead2.googlesyndication.com'),
      detectAdBlockScriptAdsJs('/util/ads/ads.js'),
      detectAdBlockScriptSailthruJs('/ads/sailthru.js')
    ])

    return {
      HasDetectAdBlockFetchOrXhrAdsByGoogle,
      HasDetectAdBlockFetchDoubleClick,
      HasDetectAdBlockScriptAdsByGoogle,
      HasDetectAdBlockBaitElementOrXhrGoogle,
      HasDetectAdBlockScriptAdsJs,
      HasDetectAdBlockScriptSailthruJs
    };
      
    } catch(err) {}
 }
```

## 🛠️ Required Support Files

Some detection methods require support files on your server to function properly.

### detectAdBlockFetchOrXhrAdsByGoogle
Create the file `/pagead/js/adsbygoogle.js` on your server.

### detectAdBlockBaitElementOrXhrGoogle
Create the file `/ads/pagead2.googlesyndication.com` and pass the path as a parameter to `detectAdBlockBaitElementOrXhrGoogle()`. 

**File content** (no leading or trailing spaces, just the text):
```
thistextshouldbethere
```

⚠️ **Important**: Files like `pagead2.googlesyndication.com` need to be properly configured to be accessible on your server. Test by opening the file in your browser to validate.

### detectAdBlockScriptAdsJs
Create the file `/util/ads/ads.js` and pass the path as a parameter to `detectAdBlockScriptAdsJs()`.

**File content:**
```js
// used by useDetectAdBlockScriptAdsJs.tsx to determine if ad blocker is present
var e = document.createElement('div');
e.id = 'detectAdBlocker';
e.style.display = 'none';
document.body.appendChild(e);
```

### detectAdBlockScriptSailthruJs
Create the file `/ads/sailthru.js` and pass the path as a parameter to `detectAdBlockScriptSailthruJs()`.

**File content:**
```js
var e = document.createElement('div');
e.id = 'ybVg4vsBhs';
e.style.display = 'none';
document.body.appendChild(e);
```

## 📊 Comparison with Original Library

### Key Improvements

| Feature | `@pvitor/adblock-detector` | `multi-adblock-detect` | Notes |
|---------|---------------------------|------------------------|-------|
| **React Compatibility** | React ^16.6.0 | React ^18.2.0 | Better compatibility with legacy projects |
| **API Design** | Promise-based, no callbacks | Callback-based | More modern and consistent API |
| **Timeout Handling** | Smart timeouts with guaranteed responses | No timeout in some methods | Prevents hanging promises |
| **Error Handling** | Comprehensive error management | Limited error handling | Better reliability |
| **Bundle Format** | CommonJS (Node.js compatible) | ES Modules | Better compatibility with older build tools |

### Detection Method Improvements

| Method | Improvements |
|--------|-------------|
| `detectAdBlockFetchDoubleClick` | ✅ 1-second timeout, ✅ Promise-based, ✅ Prevents multiple resolutions |
| `detectAdBlockFetchOrXhrAdsByGoogle` | ✅ Flexible URL parameter, ✅ Guaranteed response, ✅ Definitive true/false state |
| `detectAdBlockScriptAdsByGoogle` | ✅ Script cleanup after loading, ✅ Explicit success/failure states |
| `detectAdBlockScriptAdsJs` | ✅ Proper useEffect implementation, ✅ Modern API with timeout |
| `detectAdBlockScriptSailthruJs` | ✅ URL parameter support, ✅ Modern Promise-based API |

## ⚠️ Known Limitations

- **uBlock Origin** and **Brave Shield** are not currently detected
- Support for these blockers will be added in future versions

## 📄 License

This code is derived from several sources. All original code is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). See full text at: https://github.com/arjun-menon/multi-adblock-detect/blob/master/LICENSE.md

### Attribution

The detection algorithms are derived from multiple sources:

- **`detectAdBlockBaitElementOrXhrGoogle`**: [just-detect-adblock](https://github.com/wmcmurray/just-detect-adblock) (no license information)
  - Originally derived from: [BlockAdBlock](https://github.com/sitexw/BlockAdBlock) (MIT license)
- **`detectAdBlockFetchDoubleClick`**: [adblock-detect-react](https://github.com/aruniverse/adblock-detect-react/blob/master/adblock-detect-react) (no license information)
- **Three algorithms from**: [Detecting uBlock Origin and Adblock Plus](https://incolumitas.com/2020/12/27/detecting-uBlock-Origin-and-Adblock-Plus-with-JavaScript-only/) (no license information)
  - `detectAdBlockFetchOrXhrAdsByGoogle` (the "ultimate" solution)
    - Derived from: [adblock-detect-javascript-only](https://github.com/NikolaiT/adblock-detect-javascript-only/blob/master/index.js) (no license information)
  - `detectAdBlockScriptAdsByGoogle` (first solution in the article)
  - `detectAdBlockScriptSailthruJs` (updated solution from May 25th 2022)
- **`detectAdBlockScriptAdsJs`**: In-house solution (may be removed due to low effectiveness)

The wrapper code is released under Apache 2.0.