How-To/Instructional

JavaScript Integration for non-WordPress Sites

Last updated a few days ago

Introduction

JavaScript integration is a high-performance, browser-based solution that connects your site to Ezoic's AI engine. By placing a lightweight script directly into your site's HTML, you enable real-time ad personalization and competitive bidding without needing complex configuration. Pages remain responsive and fast because the Ezoic library manages ad delivery and layout optimization entirely within the visitor's browser.

Faster option: Try the AI Setup Assistant. The Ezoic AI Setup Assistant can look at your site and give you the exact integration code for your setup, whether you're on plain HTML, React, Vue, Angular, Next.js, or another framework. If you already use an AI coding tool like Cursor, Claude Code, or ChatGPT, you can connect the Setup Assistant to it and let your agent add the code inside your editor. Open the Setup Assistant in your dashboard at EzoicAds > AI Setup Assistant, or continue with the manual steps below.

Instructions

Step 1: Add the Header Scripts

Place these scripts at the very top of your site's <head> tag so the engine is ready to serve ads as soon as the page begins to load.

Privacy Script. Manages Consent Management and must load first to keep your site compliant with global privacy regulations.

<script data-cfasync="false" src="https://cmp.gatekeeperconsent.com/min.js"></script>
<script data-cfasync="false" src="https://the.gatekeeperconsent.com/cmp.min.js"></script>

Ezoic Header Script. Loads the core Ezoic library asynchronously so there's no impact on your page load speed.

<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
<script>
    window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
</script>
<script src="//ezoicanalytics.com/analytics.js"></script>

Step 2: Add Ad Placements

Now that Ezoic's scripts are loaded, place ads. There are two ways to do this:

Simple Setup (Recommended). Paste a small script wherever you want an ad. The ad appears right there. No dashboard configuration and no placement IDs required.
Using Placement IDs. Create placements in your dashboard when you need advanced control over sizing, styling, or per-location settings.

Most sites should start with Simple Setup. Move to Placement IDs when you need one of the specific controls it offers.

Simple Setup: No Placement IDs (Recommended)

Paste this snippet wherever you want an ad. The ad appears exactly where the script is, with nothing to create in the dashboard:

<script>
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds({ sizes: "300x250" });
    });
</script>

sizes is optional. Leave it out (ezstandalone.showAds({})) and Ezoic picks the best-paying size configured for that position on the visitor's device type. Size selection doesn't measure your container, so if the spot is narrower than your main content column, pass sizes to keep ads that fit. You can pass a single size or an array like sizes: ["300x250", "336x280"].

Sizes must be fixed WIDTHxHEIGHT values. Fluid (native-style) ads are added automatically where the placement is eligible. You don't request them as a size (see the optional fluid attribute below to control them).

Place one snippet per ad spot: one above your content, one between paragraphs, one in your sidebar. Each snippet places one ad at its own position. Ads never stack, so to show several ads, place several snippets at different positions on your page.

Different Sizes Per Device

Use mobile_sizes and desktop_sizes to split sizes by device in one call. sizes stays the default for any device you don't override:

<script>
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds({
            mobile_sizes: ["300x250", "336x280"],
            desktop_sizes: ["728x90", "970x250"],
        });
    });
</script>

Tablets use tablet_sizes if given, otherwise desktop_sizes, otherwise sizes. These attributes work on id-based calls too.

Placing Ads From JavaScript

If your ad spots aren't marked by inline scripts (for example, single-page apps, dynamically loaded content, or infinite scroll), tell showAds where to place the ad:

anchor. Pass an element or CSS selector. The ad is inserted right after it: ezstandalone.showAds({ sizes: "300x250", anchor: "#after-comments" })
location. Pass a named position Ezoic resolves for you: ezstandalone.showAds({ location: "under_first_paragraph" }). Supported locations include top_of_page, under_page_title, under_first_paragraph, under_second_paragraph, mid_content, long_content, longest_content, bottom_of_page, and the sidebar family sidebar, sidebar_middle, sidebar_bottom.
Neither. The ad is appended at the end of your content, which suits feeds and infinite scroll where new content keeps arriving.

Marking Ad Spots in Your HTML

Instead of one script per spot, you can mark ad spots with plain elements and make a single showAds call with a CSS selector. Each matched element hosts one ad, and per-ad settings come from data-* attributes on the element:

<div class="ezoicad" data-sizes="300x250,336x280"></div>
<div class="ezoicad" data-sizes="300x250" data-fluid="false"></div>
<div class="ezoicad" data-devices="desktop" data-sizes="728x90"></div>

<script>
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds(".ezoicad");
    });
</script>

The ad is placed inside the matched element, so you style and position the container however you like. Available data-* attributes: data-sizes, data-mobile_sizes, data-desktop_sizes, data-tablet_sizes (comma-separated size lists), data-devices (comma-separated device list), data-fluid, data-required, and data-location (a named location label for reporting, where the ad still renders inside the element).

Elements are only used once. Calling showAds(".ezoicad") again, after a route change in a single-page app or after appending new content in an infinite scroll, skips the spots that already have ads and only fills newly added elements.

Optional Attributes

You don't need any of these for a basic setup. They're per-ad controls for when you want them:

devices. Only place the ad on the listed device types ("mobile", "tablet", "desktop"). On other devices the snippet does nothing (no ad, no request): ezstandalone.showAds({ devices: ["desktop"], sizes: "728x90" })
class and style. A CSS class or inline style applied to the ad's container div, so you can style the spot without owning the markup: ezstandalone.showAds({ sizes: "300x250", class: "my-ad-frame", style: "margin: 24px auto;" })
fluid. Controls fluid (native-style) ads for this spot. fluid: false prevents them even where they'd normally be eligible (useful when variable-height creatives break your layout). fluid: true allows them where your configuration would otherwise disable them. Safety limits (above-the-fold positions, fixed-size frames) always apply.
required. Id-less ads default to required: true, meaning the ad serves even past the page's automatic ad-density cap. Pass required: false to let Ezoic skip the ad when the page already carries enough ads.

Working examples of every integration style (id-less, placement IDs, Angular, React, Vue, and Web Games) are live at examples.ezoic.com with copyable source. Using a JavaScript framework? See the official Framework SDKs for Angular, React, and Vue.

Using Placement IDs: Advanced Control

Placement IDs are useful when you want more control than Simple Setup provides:

Responsive sizing. Configure different size lists per placement and adjust them per device in the dashboard.
Styling and exact positioning. You own the placeholder div, so you decide exactly where it sits in your markup and layout.
Per-location settings. Every placement gets its own entry in your dashboard for controlling behavior, running A/B tests, and reading per-placement reporting.
Programmatic control. Target specific placements with refreshAds, destroyPlaceholders, and the required flag (advanced usage).

First, create ad placements in your Ezoic Dashboard, or work with your Ezoic Onboarding Specialist for optimized placement recommendations.

Once you have your ad placement IDs, add this code wherever you want ads to appear:

<div id="ezoic-pub-ad-placeholder-101"></div>
<script>
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds(101);
    });
</script>

Replace 101 with your actual placement ID from the dashboard. Insert this code for each ad location on your site.

Pages with multiple placements should pass all placement IDs into a single showAds() call. This reduces server requests and improves loading speed. Example: ezstandalone.showAds(101, 102, 103, 104).

Do not add any styling to the placeholder div. Adding styles or reserving space for the ad may result in empty white space if an ad doesn't load, and the AI needs the flexibility to test different ad sizes in real time to find the highest-paying option for that visitor.

Calling ezstandalone.showAds() without any arguments will call the function for every placeholder div that exists on that page.

To make sure Ezoic ads work correctly on your site, remove any leftover ad code from other ad networks before going live.

Step 3: Verification and the Ramp Up Period

Once your scripts are active and Google has approved your MCM status, your ads will go live automatically. Ezoic will then begin the Ramp Up Period, where the AI collects data to maximize your long-term EPMV.

Using the JavaScript Debugger. To confirm your setup is optimal, append ?ez_js_debugger=1 to any URL on your site. A diagnostic modal will appear and show you:

Script Detection. Verifies the Ezoic library is loading correctly in the browser.
Placeholder Count. Confirms the system sees all the locations you've created.
Ad Status. Shows real-time request and fill data for each position.

Advanced Documentation

Full developer documentation, including framework-specific SDKs (Angular, React, Vue), advanced APIs, and dynamic content handling, is at docs.ezoic.com.

Troubleshooting

Ads aren't showing yet. Verify your MCM status in the dashboard. If Google is still reviewing your domain, the Ezoic script will remain idle. Also make sure your Ads.txt file includes the necessary Ezoic authorized seller entries.

Handling Layout Shifting (CLS). With placement-ID-based integration, Ezoic doesn't automatically reserve space for the ad unit before it loads. To prevent your content from jumping when an ad appears, wrap your placeholder div in a container with a defined min-height (e.g., min-height: 250px;) sized for the most common ad in that specific location. This gives a stable user experience and better Core Web Vitals scores. Id-less Simple Setup handles container sizing automatically and doesn't require this workaround.

Dynamic Content. If your site loads content via AJAX or uses infinite scroll, you need to re-call ezstandalone.showAds() whenever new content is injected so the engine knows about the new placements. Id-less calls that use anchor or a CSS selector are the cleanest fit for these scenarios. See Dynamic Content in the developer documentation for more.

Contact Information for Further Assistance

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

Was this article helpful?