npm package: @codepenguin/adsense-simulator
Description: A lightweight development simulator for Google AdSense that mimics ad slot behavior locally.
Author: clowneon1
Latest version: 3.0.0

# @codepenguin/adsense-simulator

A lightweight **development tool that simulates Google AdSense behavior locally**.

This allows developers to test **ad placements, responsive layouts, and integration logic** without loading real Google ads.

The simulator reproduces key runtime behaviors of AdSense while running **entirely in the browser with no external network requests**.

⚠️ **Development use only. Do not use in production.**

---

# Features

The simulator reproduces important behaviors of Google AdSense:

- `.adsbygoogle` slot detection
- `adsbygoogle.push()` queue handling
- responsive ad sizing
- container-based ad selection
- dynamic DOM insertion detection
- SPA navigation support
- back/forward navigation handling
- bfcache (back-forward cache) support
- click simulation
- ad metadata inspection
- optional blocking of the real AdSense script

---

# Installation

## npm

```bash
npm install @codepenguin/adsense-simulator
```

Then import it in your development environment:

```javascript
import "@codepenguin/adsense-simulator";
```

---

## CDN

You can also use the simulator directly in static HTML pages.

```html
<script src="https://cdn.jsdelivr.net/npm/@codepenguin/adsense-simulator/dist/adsense-simulator.min.js"></script>
```

---

# Example Ad Slot

Use normal AdSense markup.

```html
<ins
  class="adsbygoogle"
  style="display:block;width:300px;height:250px"
  data-ad-client="ca-pub-demo"
  data-ad-slot="123456"
>
</ins>

<script>
  (adsbygoogle = window.adsbygoogle || []).push({});
</script>
```

The simulator will render a mock ad displaying useful debug information.

Example:

```
adsense-simulator
client: ca-pub-demo
slot: 123456
size: 300x250
format: fixed
```

---

# Responsive Ads

Responsive slots are supported.

```html
<ins
  class="adsbygoogle"
  style="display:block"
  data-ad-client="ca-pub-demo"
  data-ad-slot="123456"
  data-ad-format="auto"
>
</ins>
```

The simulator chooses an appropriate ad size based on container width.

---

# Dynamic Ads (SPA / React / Astro)

The simulator automatically detects dynamically inserted ads.

```javascript
const ad = document.createElement("ins");

ad.className = "adsbygoogle";
ad.style.display = "block";
ad.style.width = "300px";
ad.style.height = "250px";

ad.setAttribute("data-ad-client", "ca-pub-demo");
ad.setAttribute("data-ad-slot", "123456");

document.body.appendChild(ad);

adsbygoogle.push({});
```

MutationObserver automatically triggers a scan.

---

# Click Simulation

Clicking a simulated ad opens a mock advertiser page displaying ad metadata.

Example data shown:

- client
- slot
- ad size
- format
- container width
- page path
- timestamp

This helps verify correct ad configuration.

---

# Blocking Real AdSense Script

During development you may want to prevent the real AdSense script from loading to avoid conflicts with the simulator.

Use the `data-remove-google-ads` attribute on the script tag:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@codepenguin/adsense-simulator/dist/adsense-simulator.min.js"
  data-remove-google-ads="true"
></script>
```

When enabled, the simulator intercepts attempts to load:

```
https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
```

and prevents it from downloading.

> ⚠️ **Note:** Query string parameters (e.g. `?removeGoogleAds=true`) do **not** work
> when loading from jsDelivr or unpkg — CDNs strip query strings before serving files.
> Always use the `data-remove-google-ads="true"` attribute instead.

---

# Console Output

When the simulator starts you will see:

```
adsense-simulator: started { removeGoogleAds: "true" }
```

If the real AdSense script is blocked:

```
adsense-simulator: blocked Google AdSense script
```

---

# Supported Ad Sizes

The simulator supports common AdSense sizes including:

- 320×50
- 468×60
- 728×90
- 300×250
- 336×280
- 160×600
- 300×600
- 970×90
- 970×250

Responsive ads automatically choose the closest match.

---

# Runtime Behavior

The simulator processes ads using a queue system similar to AdSense:

```
adsbygoogle.push()
        ↓
queue intercept
        ↓
slot scanning
        ↓
ad rendering
```

Dynamic content and SPA navigation are handled via MutationObserver.

---

# Known Limitations

### Blocking real AdSense is best-effort

The `data-remove-google-ads` blocker uses a `MutationObserver` to detect and remove AdSense script tags. Because `MutationObserver` fires asynchronously (after the current JS task), there is a small window where the browser may have already started fetching the script before removal.

For guaranteed blocking in a dev environment, add a Content Security Policy to your dev server:

```
Content-Security-Policy: script-src 'self' 'unsafe-inline'
```

This prevents the AdSense script from loading at the network level regardless of how it is injected.

---

# What This Simulator Does NOT Replicate

This tool does not simulate Google's ad network infrastructure.

It does **not provide**:

- real ads
- advertiser targeting
- auctions
- revenue tracking
- fraud detection
- AdSense account validation

Those systems run exclusively on Google's servers.

---

# License

MIT

---

# Repository

https://github.com/clowneon1/adsense-simulator