Advanced

Overview

EzoicAds provides advanced features that allow publishers to fine-tune the behavior of the ad library. These features can be used to customize the behavior of the ad library to better suit the needs of your site.

Configurable Options

There are configurable options available in EzoicAds that can be used to customize the behavior of the ad library. These options can be set using the ezstandalone.config() function.

Setting Configuration Options

To set configuration options, use the following syntax:

ezstandalone.cmd.push(function() {
    ezstandalone.config({
        // Configuration options go here
    });
});

Important: These configuration options must be set after initialization of the EzoicAds header scripts and before calling ezstandalone.showAds().

Available Options

Limit Cookies

When enabled, the Limit Cookies feature ensures that only essential cookies required by Ezoic are included by default. This provides greater control over user privacy and helps with compliance to various data protection regulations.

To enable Limit Cookies:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ limitCookies: true });
});

Anchor Ad Position

Allows you to change the position of the Anchor Ad to be at the top or bottom of the page. Acceptable values are 'top' or 'bottom'. The Anchor Ad will be located at the bottom of the page by default.

For example to set the anchor ad position to be at the top of the page:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ anchorAdPosition: "top" });
});

Anchor Ad Expansion

Allows you to set the expansion behavior for collapsible anchor ads on mobile devices. Collapsible anchor ads are allowed to expand by default.

To disable anchor ad expansion:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ anchorAdExpansion: false });
});

Disable Interstitial

Allows you to completely disable all interstitial ads on your site. When enabled, no interstitial ads (including vignette ads) will be displayed.

To disable all interstitial ads:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ disableInterstitial: true });
});

Disable Video

Allows you to disable Ezoic video players and video ads on your site. When enabled, no Ezoic video players will be inserted into your pages.

To disable video:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ disableVideo: true });
});

Disable Side Rails

Side rail ads display in the unused gutter space to the left and right of your page content on wide screens. You can disable each side independently.

To disable both side rails:

ezstandalone.cmd.push(function() {
    ezstandalone.config({
        disableLeftSideRail: true,
        disableRightSideRail: true
    });
});

To disable only the left side rail:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ disableLeftSideRail: true });
});

Disable Floating Sidebar

Allows you to disable floating (sticky) sidebar ads, which remain visible in the sidebar as the user scrolls.

To disable floating sidebar ads:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ disableSidebarFloating: true });
});

Vignette Ads

Vignette ads (also known as interstitial ads) are full-screen ads that display between page content or during natural transition points. You can control their display behavior on different device types.

By default, vignette ads follow your site's global settings. Use these options to override the behavior for specific device types:

Enable vignette ads on desktop only:

ezstandalone.cmd.push(function() {
    ezstandalone.config({
        vignetteDesktop: true,
        vignetteMobile: false,
        vignetteTablet: false
    });
});

Disable vignette ads on mobile devices:

ezstandalone.cmd.push(function() {
    ezstandalone.config({ vignetteMobile: false });
});

Enable vignette ads on all devices:

ezstandalone.cmd.push(function() {
    ezstandalone.config({
        vignetteDesktop: true,
        vignetteMobile: true,
        vignetteTablet: true
    });
});

More options will be added in the future. Please check back for updates.

Tracking Data

If you would like to track data even on pages that are not showing ads you can include the script below. This is specifically helpful in the starting stages of testing when you are not ready to show ads yet.

<script src="//ezoicanalytics.com/analytics.js"></script>

Splitting Traffic

Unlike our other integration methods, splitting traffic happens clientside.

Using the ezstandalone.isEzoicUser function, you can split traffic on a percentage of your traffic.

Example

Below is an example of splitting 50 percent of your traffic with Ezoic.

<script type="text/javascript">
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(function() {
        var percentageToRunEzoic = 50;
        if(ezstandalone.isEzoicUser(percentageToRunEzoic)) {
            ezstandalone.showAds(100, 101);
        } else {
            // Normal ad code execution
        }
    });
</script>

ShowAds Advanced Usage

The basic placement snippet on Ad Placements lets Ezoic choose the right size automatically. Use these options only when you need custom sizing, JavaScript placement control, or placement IDs from the dashboard.

Custom Sizing

Pass sizes when a spot must only request specific fixed sizes. You can provide a single WIDTHxHEIGHT value or an array of values:

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

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

If sizes is omitted, Ezoic uses its default behavior to determine the ad size. Fluid (native-style) ads are added automatically where the placement is eligible, so you do not request them as a fixed size.

Different Sizes Per Device

Use mobile_sizes, tablet_sizes, and desktop_sizes to split allowed sizes by device. sizes remains the fallback for any device type you do not override:

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

Tablets use tablet_sizes if provided, otherwise desktop_sizes, otherwise sizes.

Placing Ads From JavaScript

If your ad spots are not marked by inline scripts, such as in single-page apps, dynamically loaded content, or infinite scroll, tell showAds where to place the ad:

• anchor — an element or CSS selector. The ad is inserted right after it: ezstandalone.showAds({ sizes: "300x250", anchor: "#after-comments" })
• location — 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 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 can style and position the container. Available data-* attributes include data-sizes, data-mobile_sizes, data-desktop_sizes, data-tablet_sizes, data-devices, data-fluid, data-required, and data-location.

Elements are only used once: calling showAds(".ezoicad") again after a route change or after appending new content skips spots that already have ads and only fills newly added elements.

Optional Per-Ad Attributes

You can pass these attributes in the object form of showAds:

• id — the unique placement ID where the ad should be shown. When omitted, the ad is placed where the calling script is.
• devices — only place the ad on the listed device types ("mobile", "tablet", "desktop"). On other devices the snippet does nothing: ezstandalone.showAds({ devices: ["desktop"], sizes: "728x90" }).
• class / style — a CSS class or inline style applied to the ad's container div: ezstandalone.showAds({ sizes: "300x250", class: "my-ad-frame", style: "margin: 24px auto;" }).
• fluid — control fluid ads for this spot. fluid: false prevents them where variable-height creatives would break your layout; fluid: true allows them where your configuration would otherwise disable them. Safety limits still 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.

Using Placement IDs

Placement IDs are useful when you want dashboard-level control for specific ad spots, such as per-location reporting, experiments, or custom size settings. First, create ad placements in your Ezoic Dashboard, or work with your Ezoic Onboarding Specialist for optimized placement recommendations.

Once you have your placement IDs, add the matching placeholder div where the ad should appear and call showAds with that ID:

<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.

Placement ID And Batch Examples

showAds can accept an array of objects when you want to configure several placements in one call:

<script>
var placeholders = [
    { id: 103, required: true, sizes: ['336x280', '126x126'] },
    { id: 104, sizes: '1000x450' },
    { id: 105, required: true },
];

ezstandalone.showAds(placeholders);
</script>

In this example:

1. Placeholder 103 requests either 336x280 or 126x126 and is required.
2. Placeholder 104 requests 1000x450 if Ezoic decides this ad should be shown.
3. Placeholder 105 is required and has no size request, so Ezoic decides the best size for this placeholder.

Notes

• Sizes must be fixed WIDTHxHEIGHT values.
• If sizes are specified, the ad will only display when an ad of the specified sizes is available.
• If sizes are omitted or left empty, Ezoic uses its default behavior to determine the ad size.
• Use custom sizing only when your layout needs it. The basic setup is recommended for most ad placements.

RefreshAds

refreshAds allows for placeholders to be refreshed without needing to call destroyPlaceholders and showAds. This is useful for sites with dynamic content or infinite scroll where the content changes but the placeholders remain the same.

Multiple placeholders can be passed in as comma-separated list of IDs or as an array of IDs.

Example

<script>
    ezstandalone.cmd.push(function() {
        ezstandalone.refreshAds(101, 102)
    });
</script>