Using the Debugger

Introduction

The JavaScript Integration Debugger is a built-in diagnostic tool that lets you see exactly how Ezoic is running on any page of your site. Open any page with a URL parameter, and a modal appears that shows which ad placements loaded, what order your scripts ran in, how fast each step completed, and whether anything in your setup is actively hurting performance. No browser extension required and no impact on real visitors.

Use it to confirm placements are rendering where you expect, verify a new integration is wired up correctly, measure how fast Ezoic's scripts start on a given page, and catch common setup problems like a lazily-loaded script or a mis-ordered consent snippet.

Instructions

Step 1: Enable the Debugger

Append the following query parameter to any URL on your site:

?ez_js_debugger=1

Example: https://www.yoursite.com/?ez_js_debugger=1

Once the page loads, the debugger appears as a green panel pinned to the bottom center of the screen. It stays on top of anchor ads and video ads so nothing overlaps, and the tables and tabs inside are swipeable so you can test comfortably on an actual mobile device.

The debugger has three tabs: Overview, Placeholders, and Timing.

Step 2: Use the Placeholders Tab to Verify Ad Locations

The Placeholders tab lists every ad placement on the current page and lets you see them visually overlaid on the page itself.

Click the eye icon at the top right of the debugger panel to turn on the Placement Highlighter. The highlighter draws a colored border around every placement on the page:

• Green border: the ad loaded successfully.
• Blue border: the placeholder was called, but no ad was selected or filled.
• Orange border: the placeholder exists on the page but was not called.
• Purple border (with icon): this is a Qubit placement, meaning it was automatically inserted by Ezoic's dynamic placement system rather than hard-coded into your HTML. Qubit placements also show a small icon in the debugger's placement list so you can tell them apart from the placements you've placed yourself.

The placeholder ID appears in the top-left corner of each highlighted placement so you can tie what you see on the page back to the corresponding settings in your dashboard.

The Placeholders tab table itself shows each placement with its ID, named location, whether the ID was selected for ad insertion, and the associated ad unit name and size. Any placeholder present in your HTML but not included in the most recent ad request appears under Unused Placeholders so you can tell when a defined placement isn't being used.

Step 3: Use the Timing Tab to Check Script Performance

The Timing tab shows how fast Ezoic starts on the current page load, measured in milliseconds from the start of navigation. Each metric is displayed as a card with its measured time:

• First Ezoic script requested: the moment the browser begins to request sa.min.js.
• sa.min.js initialization started: when the Ezoic library finishes loading and begins initializing.
• First showAds call: the moment your page issues its first ezstandalone.showAds() call.
• First ad request: when the first actual ad request is sent to Ezoic's servers.

The card colors indicate measurement status:

• Green: the metric was measured.
• Yellow: the step hasn't happened yet.
• Gray: the step wasn't captured on this page load, or isn't used on this page.

Hover the (i) icon on any card for a description of exactly what the metric measures.

Underneath the cards, a chronological timeline shows every ezstandalone method called during the page load with the arguments passed. This is useful for confirming that scripts are initializing in the order you expect and that nothing is firing after window.load when it should be firing before.

The window.load time appears alongside the cards for comparison so you can see how your script timing lines up with the browser's full page load.

Step 4: Review Flagged Setup Problems

The Timing tab actively looks for common integration mistakes and flags them with red callouts. When issues are present, the Timing tab shows a red count badge so you know something is worth your attention.

The problems the debugger currently catches:

• sa.min.js loaded late (after window.load). The Ezoic script was requested after the page finished loading, which almost always means a tag manager, lazy-loader, or script that delays other scripts is injecting it late. Fix: place the Ezoic scripts directly in the page's <head> so ads can start as soon as possible.
• sa.min.js included more than once. The page has multiple sa.min.js script tags. Fix: remove the duplicates so the script loads once from the page's <head>.
• Consent script placed after sa.min.js. The consent management script tag comes after sa.min.js on the page. Fix: load the consent script first, then sa.min.js, as the JavaScript integration guide describes.
• Cloudflare Rocket Loader taking over sa.min.js. Cloudflare's Rocket Loader is intercepting Ezoic's script and changing how it loads. Fix: exclude Ezoic scripts from Rocket Loader at your Cloudflare dashboard.

For the full developer-facing reference on the debugger (including every section, every check, and advanced troubleshooting patterns), see the EzoicAds Troubleshooting documentation.

FAQs

Is a browser extension required to use the debugger?

No. The debugger is activated by the URL parameter only. There's nothing to install.

Does enabling the debugger affect what my regular visitors see?

No. The ?ez_js_debugger=1 parameter only activates when manually appended to a URL. Visitors who load your site normally won't see it.

Can I use the debugger to see how ads appear on mobile?

Yes. Open the page with the debugger parameter on your actual mobile device. The tables and tabs are swipeable so the full debugger is usable on a touch interface. You can also use your browser's developer tools to simulate different screen sizes on desktop.

How do I adjust the size or settings of a placement I see in the debugger?

Note the placeholder ID shown in the top left of the highlighted placement, then find it in your dashboard. WordPress plugin users can find placements under the Ad Placements tab in the plugin. Manual JavaScript users can navigate to EzoicAds > Placeholders to make changes.

What's the difference between a regular placement and a Qubit placement?

Regular placements are the placements you've defined in your HTML or in your dashboard. Qubit placements are inserted automatically by Ezoic's dynamic placement system based on what works best for your site. In the debugger, Qubit placements are highlighted in purple and show a small icon so you can tell them apart from the placements you've set up yourself.

What happened to the Events tab?

The Events tab has been merged into the Timing tab. The chronological list of ezstandalone method calls (what used to be the Events tab's main content) now appears underneath the Timing cards, alongside the script timing measurements. This gives you both the raw event order and the overall performance picture in one place.

What should I do if the debugger shows my scripts loaded late?

Follow the fix noted on the red callout. In most cases, the correct answer is to place the Ezoic header scripts directly in your page's <head> tag, not inside a tag manager, lazy-loader, or anything else that delays them. See JavaScript Integration for non-WordPress Sites for the recommended placement.

Contact Information for Further Assistance

If you need further assistance using the JavaScript Integration Debugger, please log in via support.ezoic.com to make use of our dedicated resources for support. We're here to help!