Documentation

Overview

The simulator reproduces key AdSense runtime behaviors entirely in the browser with no external network requests. It detects .adsbygoogle slots, intercepts the adsbygoogle.push() queue, renders mock ads with real debug metadata, and handles SPA navigation and bfcache restoration automatically.

Installation

npm

npm install @codepenguin/adsense-simulator

CDN

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

Quick Start

Import in your development entry point:

import "@codepenguin/adsense-simulator";

Then use standard AdSense markup. The simulator handles the rest:

<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 renders a mock ad showing: client, slot, size, and format.

Data Attributes

Ad Sizes

All 12 standard IAB sizes supported:

Fixed slots: set explicit width and height in the inline style. The simulator uses those dimensions directly.

Responsive Ads

Set data-ad-format="auto" to let the simulator pick the best size based on container width:

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

Ad Layouts

Layout ads use fluid dimensions relative to their container width:

<ins
  class="adsbygoogle"
  style="display:block"
  data-ad-client="ca-pub-demo"
  data-ad-slot="123456"
  data-ad-format="fluid"
  data-ad-layout="in-article"
></ins>

Queue API

The simulator installs its own window.adsbygoogle array with a custom push() interceptor. Calling (adsbygoogle = window.adsbygoogle || []).push() drains the queue and triggers a slot scan.

Internal flow:

adsbygoogle.push()
       ↓
queue intercept
       ↓
slot scanning (.adsbygoogle elements)
       ↓
ad rendering (mock ad injected into slot)

Dynamic Insertion

A MutationObserver watches document.documentElement (not document.body) so it survives full body replacements by SPA frameworks. Slots inserted via JavaScript are detected and rendered automatically without any extra .push() call.

const ad = document.createElement('ins')
ad.className = 'adsbygoogle'
ad.style.cssText = 'display:block;width:300px;height:250px'
ad.dataset.adClient = 'ca-pub-demo'
ad.dataset.adSlot   = '123456'
document.body.appendChild(ad)
// MutationObserver detects it — no .push() needed

The observer also watches attribute mutations — frameworks that insert the shell <ins> first and set data-ad-client / data-ad-slot during hydration are handled correctly.

SPA Navigation

The simulator patches history.pushState and history.replaceState and listens for the popstate event. On every route change it runs a full reinit cycle:

teardown (disconnect observer, reset queue, clear slots)
       ↓
startDomObserver  (re-attach on documentElement)
       ↓
initQueue         (push() hook live immediately)
       ↓
scanSlots         (render all visible slots)

pushState / replaceState — reinit is immediate because the framework mounts content synchronously.

popstate (back/forward) — reinit is deferred with multiple rAF + setTimeout passes because the browser fires the event before the framework restores the DOM.

bfcache Support

The pageshow event with event.persisted === true is the only reliable signal for back-forward cache restoration (popstate may not fire). The simulator listens for it and runs the same deferred reinit path.

Script Blocking

Add data-remove-google-ads="true" to the CDN script tag to activate all 4 blocking layers:

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

Layer numbers match the source code comments — Layer 2 is intentionally absent (reserved for future use).

CSP Recommendation

The MutationObserver blocker is best-effort — it fires asynchronously, leaving a small window where the browser may have started fetching adsbygoogle.js. For guaranteed blocking at the network level, add a Content Security Policy to your dev server:

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

Click Simulation

Clicking any rendered mock ad opens a new tab with a debug page showing full ad metadata:

Console Output

When the simulator initialises you will see:

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

If real AdSense is blocked:

adsense-simulator: blocked Google AdSense script (createElement intercept)
adsense-simulator: blocked Google AdSense script (MutationObserver)

Slot validation errors (missing attributes):

adsense-simulator: data-ad-client and data-ad-slot are required

Known Limitations

The slotScanner retries up to 5 times over 2 seconds for slots missing data-ad-client or data-ad-slot — after that the slot is marked as errored and skipped.

Not Replicated

The simulator does not replicate Google's ad network infrastructure. The following are intentionally excluded:

• Real ads or advertiser content
• Auction and bidding logic
• Advertiser targeting
• Revenue tracking
• Fraud detection
• AdSense account validation

These systems run exclusively on Google's servers and cannot be replicated client-side.