Ezoic

https://docs.ezoic.com/
Admin
Ezoic is a client-side ad management platform that allows publishers to control ad placements on...
Tokens:23,962
Snippets:272
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Full Rewarded Ad Example with All Options

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This comprehensive example showcases all available configuration options for `requestWithOverlay`, serving as a reference for integrating various features like custom headers, bodies, accept/cancel texts, and advanced settings such as `rewardName`, `alwaysCallback`, `lockScroll`, and `rewardOnNoFill`.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestWithOverlay(
        (result) => { // Callback function
            if (result.status) {
                if (result.reward) {
                    console.log("Reward granted!");
                } else {
                    console.log("User either declined to watch the ad, or they closed the ad early.");
                }
            } else {
                console.log("Rewarded ad request failed:", result.msg);
            }
        },
        { // Text object
            header: "Watch Ad to Continue?",
            body: ["You will receive 10 credits for watching this ad.", "Click the button below to watch the ad."],
            accept: "Watch ad",
            cancel: "Cancel"
        },
        { // Config object
            rewardName: "Main Page Credits Reward",
            alwaysCallback: true,
            lockScroll: true,
            rewardOnNoFill: false
        }
    );
});
```

--------------------------------

### Basic Example

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Demonstrates the most basic usage of the `requestWithOverlay` method, utilizing default values.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestWithOverlay(grantReward, {body: ['You will get a reward for watching this ad.']});
});

function grantReward() {
    console.log("Reward granted!");
}
```

--------------------------------

### Javascript Integration for Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Full integration example including script loading, initialization, and button display logic.

```html
<script data-cfasync="false" src="https://the.gatekeeperconsent.com/cmp.min.js"></script>
<script src="https://the.gatekeeperconsent.com/ccpa/v2/standalone.js" async></script>
<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
<script>
    window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(() => {
        ezstandalone.initRewardedAds();
    });

    window.ezRewardedAds = window.ezRewardedAds || {};
    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
</script>

<button
    id="rewardedAdButton"
    style="visibility:hidden;"
    onclick="window.ezRewardedAds.requestWithOverlay(addCreditsToAccount, {body: ['You will receive 10 credits for watching this ad.']})">
    Watch Ad for 10 Credits
</button>

<script>
    // Show the button when the rewarded ad code is ready
    window.ezRewardedAds.cmd.push(() => {
        document.getElementById("rewardedAdButton").style.visibility = "visible";
    });

    // This function will be called if the reward is granted
    function addCreditsToAccount() {
        console.log("Credits added to account");
    }
</script>
```

--------------------------------

### Example URL with Email and Phone Identity

Source: https://docs.ezoic.com/docs/identity/embedding-ids-in-links

Use separate parameters for email and phone identity when passing both in the same URL. Ensure phone numbers are normalized to E.164 format before hashing.

```URL
www.publisher-website.com/mypage?utm_email=zsha256-&utm_phone=zphonesha256-
```

--------------------------------

### Initialize Rewarded Ads (Custom Configuration)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Configure specific ad types to be enabled or disabled. This example keeps anchor and video ads enabled while disabling interstitial and side rail ads.

```javascript
ezstandalone.initRewardedAds({
    anchor: true,        // Keep anchor ads
    interstitial: false, // Disable interstitial ads
    video: true,         // Keep video ads
    sideRails: false     // Disable side rail ads
});
```

--------------------------------

### Request Rewarded Ad Data

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Example cURL request to retrieve specific rewarded ad data. Replace placeholders with your actual domain and reward IDs.

```bash
curl -X POST "https://api-gateway.ezoic.com/gateway/bdaservices/getCustomData/?developerKey=YOUR_DEVELOPER_KEY" \
-H "Content-Type: application/json" \
--data '{
	"StartDate": "2025-08-12",
	"EndDate": "2025-08-13",
	"Platform": "ALL",
	"DomainId": YOUR_DOMAIN_ID,
	"DimensionColumns": [
        {
            "Data": "reward_id",
            "Type": "string"
        },
        {
            "Data": "reward_status",
            "Type": "string"
        },
        {
            "Data": "is_matched",
            "Type": "number"
        }
    ],
    "MetricColumns":[
        {
            "Data": "reward_revenue",
            "Type": "number"
        }
    ],
    "Order":{
        "ColumnNumber":0,
        "Direction":"DESC"
    },
    "Filters": [
        {
            "Type": "INCLUDE",
            "FilterKey": "reward_id",
            "OperationId": "EXACTLY",
            "FilterValue": "YOUR_REWARD_ID"
        }
    ]
}'
```

--------------------------------

### Handle Route Events with Pages Router

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/nextjs

Implement route change handling in `_app.tsx` for the Pages Router. This setup listens for `routeChangeComplete` events and uses the `runEzoic` helper to refresh ads by destroying old placeholders and showing new ones.

```typescript
import { useEffect } from "react";
import { useRouter } from "next/router";
import { runEzoic } from "@/lib/ezoic";

export default function App({ Component, pageProps }) {
    const router = useRouter();
    useEffect(() => {
        const handleRoute = () => {
        runEzoic(() => {
        window.ezstandalone?.destroyPlaceholders();
        window.ezstandalone?.showAds();
    });
};

router.events.on("routeChangeComplete", handleRoute);
    return () => router.events.off("routeChangeComplete", handleRoute);
}, [router.events]);

return <Component {...pageProps} />;
}


```

--------------------------------

### Display Rewarded Ad

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Displays a previously requested rewarded ad. The callback function is invoked when the ad is closed, indicating success and whether a reward was granted. This basic example does not specify a reward name.

```javascript
window.ezRewardedAds.show((closeResult) => {
    if (closeResult.status) {
        console.log("Rewarded ad closed");
        if (closeResult.reward) {
            console.log("Reward granted!");
        }
    } else {
        console.log("Failed to show rewarded ad:" + closeResult.msg);
    }
});
```

--------------------------------

### Configure Loading Overlay and Ready Callback

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Enable a loading overlay and define a callback function to handle the ad ready status.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.contentLocker(
        () => {
            downloadFile();
        },
        {
            loadingOverlay: true,
            readyCallback: (result) => {
                console.log("Ad ready status:", result.status);
            },
            callToAction: {
                header: "Download Premium File",
                body: "Support our site by watching a short ad",
                button: "Start Download"
            }
        }
    );
});
```

--------------------------------

### Initialize Rewarded Ads Command Queue (Cloud Integration)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

For cloud integration, this script initializes the command queue for Ezoic rewarded ads. Add this to the `<head>` of your site.

```html
<script>
    window.ezRewardedAds = window.ezRewardedAds || {};
    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
</script>
```

--------------------------------

### Configure Ads.txt via Server Redirects

Source: https://docs.ezoic.com/docs/ezoicads/adstxt

Use server-level redirects to point your ads.txt file to the Ezoic management service. Replace [YOUR_DOMAIN].com with your actual domain.

```apache
Redirect 301 /ads.txt https://srv.adstxtmanager.com/19390/[YOUR_DOMAIN].com
```

```nginx
server {
    location ~ /ads.txt {
        return 301 https://srv.adstxtmanager.com/19390/[YOUR_DOMAIN].com;
    }
}
```

```php
<?php
header('Location: https://srv.adstxtmanager.com/19390/[YOUR_DOMAIN].com');
exit;
?>
```

--------------------------------

### Use the Command Queue for Initialization

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Queue functions to execute automatically once the rewarded ads code is fully loaded.

```javascript
window.ezRewardedAds.cmd.push(() => {
    // Your code here
});
```

--------------------------------

### Basic Rewarded Ad Implementation

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Demonstrates the simplest usage of the rewarded ads overlay using default configuration settings.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestWithOverlay(grantReward, {body: ['You will get a reward for watching this ad.']});
});
function grantReward() {
    console.log("Reward granted!");
}
```

--------------------------------

### Load Ezoic Standalone Library

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Add this script to the `<head>` of your page to load the Ezoic standalone library. This makes the `ezstandalone` global object available.

```html
<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
```

--------------------------------

### Request Rewarded Ad with Always Callback

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use `alwaysCallback: true` to ensure the callback function is invoked regardless of whether a reward is granted. This is useful for actions that should occur even if the user declines the ad or an ad is not available. The example shows an arrow function callback passing the result to `handleRewardResult`.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestWithOverlay(
        (result) => {
            return handleRewardResult(result);
        },
        {body: ["You will receive 10 credits for watching this ad."]},
        {alwaysCallback: true}
    );
});

function handleRewardResult(result) {
    if (result.status) {
        if (result.reward) {
            takePremiumAction();
        } else {
            displayMessageToUser("Sorry, you did not receive a reward.");
        }
    } else {
        displayMessageToUser("Sorry, there was an error loading the ad.");
        // It is up to you whether to still take the premium action in this case, since the user did not have a chance to view the ad.
    }
}

function takePremiumAction() {
    console.log("Premium action taken!");
}

function displayMessageToUser(message) {
    console.log(message);
}
```

--------------------------------

### Configure EzoicAds Options

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/advanced

Use this syntax to apply configuration settings to the EzoicAds library.

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

--------------------------------

### Enable Standalone and Fetch Optimizations

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

After defining placeholders, call `ezstandalone.enable()` to fetch optimizations from Ezoic servers. This code snippet combines defining and enabling.

```javascript
window.ezstandalone = window.ezstandalone || {};
ezstandalone.cmd = ezstandalone.cmd || [];
ezstandalone.cmd.push(function() {
    ezstandalone.define(102,103,104);
    ezstandalone.enable();
});
```

--------------------------------

### ezstandalone.initRewardedAds()

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Initializes rewarded ads and optionally configures other site-wide ad types.

```APIDOC
## ezstandalone.initRewardedAds()

### Description
Initializes the rewarded ads functionality. This function can also accept a configuration object to toggle other ad types site-wide.

### Parameters
#### Request Body
- **anchor** (Boolean) - Optional - Whether to enable anchor ads. Default is true.
- **interstitial** (Boolean) - Optional - Whether to enable interstitial ads. Default is true.
- **video** (Boolean) - Optional - Whether to enable video ads (floating outstream). Default is true.
- **sideRails** (Boolean) - Optional - Whether to enable side rail ads. Default is true.

### Request Example
```javascript
ezstandalone.initRewardedAds({
    anchor: true,
    interstitial: false,
    video: true,
    sideRails: false
});
```
```

--------------------------------

### Initialize Multiple Ad Placements

Source: https://docs.ezoic.com/docs/ezoicads/implementation

Pass multiple placement IDs into a single showAds call to optimize loading speed and reduce server requests.

```javascript
ezstandalone.showAds(101, 102, 103, 104)
```

--------------------------------

### Load Ezoic Script

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/hybrid

Add this script to the <head> of your page to initialize the Ezoic library.

```html
<script async src="https://www.ezojs.com/ezoic/sa.min.js"></script>
```

--------------------------------

### Load Ads for First Article (Infinite Scroll)

Source: https://docs.ezoic.com/docs/ezoicads/dynamic-content

When the first article loads in an infinite scroll implementation, use showAds with the initial set of placeholder IDs.

```javascript
window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds(102, 103, 104);
    });
```

--------------------------------

### Define Placeholders with ezstandalone.define

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Pass placeholder IDs to `ezstandalone.define` to make them available for ad optimization. Ensure these placeholders exist in your HTML.

```javascript
window.ezstandalone = window.ezstandalone || {};
ezstandalone.cmd = ezstandalone.cmd || [];
ezstandalone.cmd.push(function() {
    ezstandalone.define(102,103,104);
});
```

--------------------------------

### Initialize content locker

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Method signature for triggering the content locker functionality.

```javascript
window.ezRewardedAds.contentLocker(action, config)
```

--------------------------------

### Initialize Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This code must be included before any other rewarded ad functions are called. It sets up the necessary command queue for the ad system.

```javascript
window.ezRewardedAds = window.ezRewardedAds || {};
window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
```

--------------------------------

### Request and show a rewarded ad

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Demonstrates the full flow of requesting an ad, prompting the user, and handling the reward callback.

```javascript
// Ensure the global object is initialized
window.ezRewardedAds = window.ezRewardedAds || {};
window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];

window.ezRewardedAds.cmd.push(() => { // Queue a command to request and show a rewarded ad
    window.ezRewardedAds.request((requestResult) => { // Request a rewarded ad
        if (requestResult.status) {
            if (confirm("Watch ad for reward?")) { // Ask the user if they want to watch the ad for a reward
                window.ezRewardedAds.show((closeResult) => {
                    if (closeResult.status) {
                        console.log("Rewarded ad closed");
                        if (closeResult.reward) {
                            console.log("Reward granted!");
                        }
                    } else {
                        console.log("Failed to show rewarded ad:" + closeResult.msg);
                    }
                });
            } else {
                // User declined to watch the ad
            }
        } else {
            console.log("Rewarded ad request failed:", requestResult.msg);
        }
    });
});
```

--------------------------------

### Initialize Ezoic Scripts in Next.js Layout

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/nextjs

Add necessary Ezoic scripts to your `app/layout.tsx` file. Initializing the `cmd` queue ensures that Ezoic commands are buffered correctly until the library is fully loaded, using `beforeInteractive` and `afterInteractive` strategies for optimal loading.

```typescript
import Script from "next/script";
import EzoicRouteHandler from "@/components/EzoicRouteHandler";

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <head>
                <Script
                    id="ezoic-cmp"
                    src="https://cmp.gatekeeperconsent.com/min.js"
                    strategy="beforeInteractive"
                    data-cfasync="false"
                />
                <Script
                    id="ezoic-cmp-2"
                    src="https://the.gatekeeperconsent.com/cmp.min.js"
                    strategy="beforeInteractive"
                    data-cfasync="false"
                />
                
                <Script
                    id="ezoic-sa"
                    src="//www.ezojs.com/ezoic/sa.min.js"
                    strategy="afterInteractive"
                />
                
                <Script id="ezoic-init" strategy="afterInteractive">
                    {`
                    window.ezstandalone = window.ezstandalone || {};
                    window.ezstandalone.cmd = window.ezstandalone.cmd || [];
                    `}
                </Script>

                <Script
                    id="ezoic-analytics"
                    src="//ezoicanalytics.com/analytics.js"
                    strategy="afterInteractive"
                />
            </head>
            <body>
                <EzoicRouteHandler />
                {children}
            </body>
        </html>
    );
}

```

--------------------------------

### Show All Placeholders

Source: https://docs.ezoic.com/docs/ezoicads/dynamic-content

Call ads in every placeholder on the page by using the showAds function without any arguments. This is useful for refreshing all ad content.

```javascript
window.ezstandalone.cmd.push(function () {
        ezstandalone.showAds();
    });
```

--------------------------------

### Initialize Rewarded Ads (All Ad Types Enabled)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This is the default usage for `initRewardedAds()`, enabling all ad types: anchor, interstitial, video, and side rails.

```javascript
ezstandalone.initRewardedAds();
```

--------------------------------

### ezstandalone.showAds

Source: https://docs.ezoic.com/docs/ezoicads/dynamic-content

Displays ads in specified placeholders or all placeholders if no arguments are provided.

```APIDOC
## ezstandalone.showAds

### Description
Displays ads in specific placeholders or refreshes all placeholders on the page. Used for dynamic page loads or new content injection.

### Parameters
#### Arguments
- **placeholderIds** (integer, optional) - A list of one or more placeholder IDs to display. If omitted, all placeholders on the page are refreshed.

### Request Example
```javascript
// Refresh all placeholders
ezstandalone.cmd.push(function () {
    ezstandalone.showAds();
});

// Display specific placeholders
ezstandalone.cmd.push(function () {
    ezstandalone.showAds(104, 105);
});
```
```

--------------------------------

### Request and Show Rewarded Ad

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Basic implementation of requestAndShow to trigger an ad and execute a callback upon reward.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestAndShow(grantReward);
});
function grantReward() {
    console.log("Reward granted!");
}
```

--------------------------------

### Advanced showAds Implementation

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/advanced

Utilize the advanced `showAds` function by passing an array of placeholder objects. Each object can specify ad `id`, `required` status, and allowed `sizes` for more granular control over ad placement and dimensions.

```APIDOC
## ShowAds Advanced Usage

### Description
The advanced `showAds` implementation accepts an array of objects, each defining attributes for ad placeholders. This allows for specifying whether an ad is required, and defining specific dimensions for the ad.

### Method
Client-side JavaScript

### Endpoint
N/A (Client-side function)

### Parameters
#### Request Body (Array of Placeholder Objects)
- **placeholders** (array) - Required - An array of objects, where each object represents an ad placeholder.
  - **id** (number) - Required - The unique identifier of the placeholder.
  - **required** (boolean) - Optional - If `true`, forces an ad to be shown in the placeholder.
  - **sizes** (string or array of strings) - Optional - Allowed ad sizes in the format '{width}x{height}'. Can be a single string or an array of strings.

### Request Example
```javascript
var placeholders = [
    { id: 103, required: true, sizes: ['336x280', '126x126'] },
    { id: 104, sizes: '1000x450' },
    { id: 105, required: true },
];

ezstandalone.showAds(placeholders);
```

### Response
N/A (This function directly manipulates the DOM to display ads.)

### Notes
- **Ad Sizes Specificity**: Specified sizes are requests; Ezoic finds the best fit. If omitted, Ezoic uses default behavior.
- **Guaranteed Placement**: `required: true` ensures ad display.
- **Size Control**: `sizes` attribute controls ad dimensions for responsive design or layout needs.
```

--------------------------------

### Initialize placeholders for infinite scroll

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Define the initial set of placeholders on page load.

```html
<script>
    window.ezstandalone = ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(function() {
        ezstandalone.define(102,103,104);
    });
</script>
```

--------------------------------

### Load Ads for Second Article (Infinite Scroll)

Source: https://docs.ezoic.com/docs/ezoicads/dynamic-content

As the user scrolls to the next article in an infinite scroll, load the next set of ads using showAds with new placeholder IDs. Ensure old placeholders are destroyed if IDs are reused.

```javascript
window.ezstandalone.cmd.push(function () {
        // call new placeholders
        ezstandalone.showAds(105, 106);
    });
```

--------------------------------

### Check if Rewarded Ads are Ready

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use the ready property to verify if the rewarded ads object is loaded before execution.

```javascript
if (window.ezRewardedAds.ready) {
    // Your code here
} else {
    // The code is not ready yet
}
```

--------------------------------

### Add Placeholder Div

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Create a `div` element with an ID prefixed by `ezoic-pub-ad-placeholder-` where an ad should appear. Do not add any styling to this div.

```html
<body>
    <div id="ezoic-pub-ad-placeholder-103">
    </div>
</body>
```

--------------------------------

### Decoupled request and show methods

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Shows how to call show() independently after a successful request, allowing for flexible UI triggers.

```javascript
// Ensure the global object is initialized
window.ezRewardedAds = window.ezRewardedAds || {};
window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];

// Request a rewarded ad
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.request((requestResult) => {
        if (requestResult.status) {
            // Ask the user if they want to view the ad. For example, display a button that calls showRewardedAd() when clicked
        } else {
            console.log("Rewarded ad request failed:", requestResult.msg);
        }
    });
});

function showRewardedAd() {
    window.ezRewardedAds.show((closeResult) => {
        if (closeResult.status) {
            console.log("Rewarded ad closed");
            if (closeResult.reward) {
                console.log("Reward granted!");
            }
        } else {
            console.log("Failed to show rewarded ad:" + closeResult.msg);
        }
    });
}
```

--------------------------------

### Add Ezoic Header Script

Source: https://docs.ezoic.com/docs/ezoicads/integration

Initialize the Ezoic ad system and analytics by placing these scripts after the privacy scripts in the <head> tag.

```html
<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>
```

--------------------------------

### Configure Advanced Ad Placeholders

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/advanced

Passes an array of objects to showAds to define placeholder IDs, required status, and specific ad sizes.

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

ezstandalone.showAds(placeholders);
</script>
```

--------------------------------

### Add Dynamic Placeholders

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/hybrid

Define ad locations by creating div elements with IDs prefixed by ezoic-pub-ad-placeholder-.

```html
<body>
    <div id="ezoic-pub-ad-placeholder-103">
    </div>
    <!-- Content -->
    <div id="ezoic-pub-ad-placeholder-104">
    </div>
</body>
```

--------------------------------

### Initialize Rewarded Ads (Disable All Other Types)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use this configuration to disable all ad types except rewarded ads. Set anchor, interstitial, video, and sideRails to false.

```javascript
ezstandalone.initRewardedAds({
    anchor: false,
    interstitial: false,
    video: false,
    sideRails: false
});
```

--------------------------------

### Send Custom Event to Ezoic

Source: https://docs.ezoic.com/docs/customevents/getting-started

Initialize the ezoicEvent queue and push a custom event name and value. Ensure these are executed within the window.ezoicEvent.queue to guarantee proper processing.

```javascript
window.ezoicEvent = window.ezoicEvent || {};
window.ezoicEvent.queue = window.ezoicEvent.queue || [];
window.ezoicEvent.queue.push(function(){
    window.ezoicEvent.add("event_name", "event_value");
});
```

--------------------------------

### Request and Show Rewarded Ad (Anonymous Function with Bind)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This method requests and displays a rewarded ad. If using an anonymous function expression for the callback and `this` context is needed, ensure to use `.bind(this)`.

```javascript
window.ezRewardedAds.requestAndShow(function(result) {
    this.handleResult(result);
}.bind(this));
```

--------------------------------

### requestWithOverlay() - Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Requests a rewarded ad and displays a call-to-action overlay asking the user if they want to view the ad. Offers customization for the overlay and reward behavior.

```APIDOC
## POST /rewardedAds/requestWithOverlay

### Description
Requests a rewarded ad and displays a call-to-action overlay asking the user if they want to view the ad. Offers customization for the overlay and reward behavior.

### Method
POST

### Endpoint
/rewardedAds/requestWithOverlay

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **callback** (Function) - Required - A function executed when the ad window is closed. The function receives a single result object with the following properties:
  - **status** (Boolean) - `true` if the ad was closed and no error occurred. `false` if an error occurred.
  - **reward** (Boolean) - Whether the reward was granted.
  - **msg** (String) - A message detailing the outcome.
  - **adInfo** (Object) - Information about the ad (only present when `status` is `true`). Contains:
    - **id** (String) - Unique identifier for the ad.
    - **estimatedPayout** (Number) - Estimated payout value for the ad.
- **config** (Object) - Optional - An object containing configuration options for the overlay and ad behavior.
  - **overlayTitle** (String) - Optional - The title displayed on the overlay.
  - **overlayMessage** (String) - Optional - The message displayed on the overlay.
  - **overlayButtonText** (String) - Optional - The text for the button on the overlay.
  - **rewardName** (String) - Optional - The name of the rewarded ad for analytics. Default is `""`.
  - **alwaysCallback** (Boolean) - Optional - Whether to call the callback function even if the reward is not granted. Default is `false`.
  - **rewardOnNoFill** (Boolean) - Optional - Whether to grant the reward in the event that an ad does not fill. Default is `false`.
  - **minCPM** (Number) - Optional - The minimum CPM for the ad to be shown. Default is `0`.

### Request Example
```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestWithOverlay(
        (result) => {
            // Handle ad result
        },
        {
            overlayTitle: "Watch Ad for Reward",
            overlayMessage: "View a short ad to earn credits.",
            overlayButtonText: "Watch Now",
            rewardName: "Overlay Reward",
            alwaysCallback: false,
            rewardOnNoFill: true
        }
    );
});
```

### Response
#### Success Response (200)
- **status** (Boolean) - Indicates if the ad request was successful.
- **reward** (Boolean) - Indicates if the reward was granted.
- **msg** (String) - A message describing the outcome.
- **adInfo** (Object) - Contains information about the ad if `status` is `true`.

#### Response Example
```json
{
  "status": true,
  "reward": false,
  "msg": "user declined ad",
  "adInfo": {
    "id": "67890",
    "estimatedPayout": 0.3
  }
}
```
```

--------------------------------

### requestWithOverlay API

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This section details the parameters and usage of the `requestWithOverlay` method for displaying rewarded ads.

```APIDOC
## POST /websites/ezoic/requestWithOverlay

### Description
Requests a rewarded ad to be displayed with an overlay. This method handles the ad request and presentation, providing a callback for completion.

### Method
POST

### Endpoint
/websites/ezoic/requestWithOverlay

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **callback** (Function): Required - A function executed when the ad request completes. Receives a result object with `status`, `reward`, `msg`, and `adInfo` properties.
- **text** (Object): Optional - An object containing text for the call-to-action overlay.
  - **header** (String, optional): The title of the call-to-action. Default is "Watch Ad to Continue?"
  - **body** (String Array, optional): The message to display in the call-to-action. Each array entry is one line. Default is no body text.
  - **accept** (String, optional): The text for the accept button. Default is "Watch ad"
  - **cancel** (String, optional): The text for the cancel button. Default is "Cancel"
- **config** (Object): Optional - An object containing configuration options for the call-to-action.
  - **rewardName** (String, optional): The name of the rewarded ad for analytics. Accepts alphanumeric characters, spaces, and some punctuation. Default is "".
  - **alwaysCallback** (Boolean, optional): Whether to call the callback function even if the reward is not granted. Default is `false`.
  - **lockScroll** (Boolean, optional): Whether to lock the scroll position when the call-to-action is displayed. Default is `false`.
  - **rewardOnNoFill** (Boolean, optional): Whether to grant the reward if an ad does not fill or an error occurs. Default is `false`.
  - **dontAsk** (Boolean, optional): If `true`, the call-to-action will not be shown, and the ad will be requested and shown immediately. Default is `false`.
  - **minCPM** (Number, optional): The minimum CPM for the ad to be shown. If no ad meets this CPM, the ad will not be shown. Default is `0`.

### Request Example
```json
{
  "callback": "grantReward",
  "text": {
    "body": ["You will get a reward for watching this ad."]
  },
  "config": {
    "rewardOnNoFill": true
  }
}
```

### Response
#### Success Response (200)
- **status** (Boolean): `true` if the ad loaded and the user had a chance to view it, `false` otherwise.
- **reward** (Boolean): Whether the reward was granted.
- **msg** (String): A message detailing the outcome.
- **adInfo** (Object): Information about the ad (only present when `status` is `true`).
  - **id** (String): Unique identifier for the ad.
  - **estimatedPayout** (Number): Estimated payout value for the ad.

#### Response Example
```json
{
  "status": true,
  "reward": true,
  "msg": "ad ready",
  "adInfo": {
    "id": "12345abcde",
    "estimatedPayout": 0.50
  }
}
```
```

--------------------------------

### Replacing a Button Event with Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Shows how to gate a button action behind a rewarded ad, with a fallback to the action if ads are unavailable or not loaded.

```html
<button id="premiumActionButton" onclick="takePremiumActionWithAd()">Take Premium Action</button>

<script>
    function takePremiumActionWithAd() {
        if (window.ezRewardedAds.ready) {
            window.ezRewardedAds.requestWithOverlay(
                takePremiumAction,
                {body: ['You will be able to take the premium action after watching an ad.']},
                {rewardOnNoFill: true}
            );
        } else {
            takePremiumAction();
        }
    }
    function takePremiumAction() {
        console.log("Premium action taken!");
    }
</script>
```

--------------------------------

### Call for Ads

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/hybrid

Trigger ad display for specific placeholders using the ezstandalone command queue.

```html
<script type="text/javascript">
    window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(function() {
        ezstandalone.showAds(103, 104);
    });
</script>
```

--------------------------------

### Request Rewarded Ad

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use this to request a rewarded ad. The callback function handles the ad's readiness status and provides ad information. Ensure this code is pushed to the `ezRewardedAds.cmd` queue.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.request((result) => {
        if (result.status) {
            console.log("Rewarded ad is ready");
            // Ask the user if they want to view the ad
        }
    });
});
```

--------------------------------

### Request and Show Rewarded Ad (Arrow Function)

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use this method to request and display a rewarded ad. The arrow function callback preserves the `this` context, which is recommended for handling ad results.

```javascript
window.ezRewardedAds.requestAndShow((result) => {
    this.handleResult(result);
});
```

--------------------------------

### requestAndShow() - Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Requests and displays a rewarded ad. The callback function is executed when the ad window is closed, providing details about the ad's status and reward.

```APIDOC
## POST /rewardedAds/requestAndShow

### Description
Requests and displays a rewarded ad. The callback function is executed when the ad window is closed, providing details about the ad's status and reward.

### Method
POST

### Endpoint
/rewardedAds/requestAndShow

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **callback** (Function) - Required - A function executed when the ad window is closed. The function receives a single result object with the following properties:
  - **status** (Boolean) - `true` if the ad was closed and no error occurred. `false` if an error occurred.
  - **reward** (Boolean) - Whether the reward was granted.
  - **msg** (String) - A message detailing the outcome.
  - **adInfo** (Object) - Information about the ad (only present when `status` is `true`). Contains:
    - **id** (String) - Unique identifier for the ad.
    - **estimatedPayout** (Number) - Estimated payout value for the ad.
- **config** (Object) - Optional - An object containing configuration options.
  - **rewardName** (String) - Optional - The name of the rewarded ad for analytics. Default is `""`.
  - **alwaysCallback** (Boolean) - Optional - Whether to call the callback function even if the reward is not granted. Default is `false`.
  - **rewardOnNoFill** (Boolean) - Optional - Whether to grant the reward in the event that an ad does not fill. Default is `false`.
  - **minCPM** (Number) - Optional - The minimum CPM for the ad to be shown. Default is `0`.

### Request Example
```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestAndShow(
        (result) => {
            if (result.status) {
                if (result.reward) {
                    console.log("Reward granted!");
                } else {
                    console.log("User closed the ad early, no reward granted.");
                }
            } else {
                console.log("Rewarded ad request failed:", result.msg);
            }
        },
        {
            rewardName: "Main Page Credits Reward",
            alwaysCallback: true,
            rewardOnNoFill: false
        }
    );
});
```

### Response
#### Success Response (200)
- **status** (Boolean) - Indicates if the ad request was successful.
- **reward** (Boolean) - Indicates if the reward was granted.
- **msg** (String) - A message describing the outcome.
- **adInfo** (Object) - Contains information about the ad if `status` is `true`.

#### Response Example
```json
{
  "status": true,
  "reward": true,
  "msg": "ad closed",
  "adInfo": {
    "id": "12345",
    "estimatedPayout": 0.5
  }
}
```
```

--------------------------------

### Display Ads with ezstandalone.display

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Call `ezstandalone.display()` after defining and enabling placeholders to render the ads on your page. This ensures ads are shown for the defined placeholders.

```javascript
window.ezstandalone = window.ezstandalone || {};
ezstandalone.cmd = ezstandalone.cmd || [];
ezstandalone.cmd.push(function() {
    ezstandalone.define(102,103,104);
    ezstandalone.enable();
    ezstandalone.display();
});
```

--------------------------------

### Cloud Integration for Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Simplified integration for environments where the rewarded ads code loads automatically.

```html
<script>
    window.ezRewardedAds = window.ezRewardedAds || {};
    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
</script>

<button
    id="rewardedAdButton"
    style="visibility:hidden;"
    onclick="window.ezRewardedAds.requestWithOverlay(addCreditsToAccount, {body: ['You will receive 10 credits for watching this ad.']})">
    Watch Ad for 10 Credits
</button>

<script>
    // Show the button when the rewarded ad code is ready
    window.ezRewardedAds.cmd.push(() => {
        document.getElementById("rewardedAdButton").style.visibility = "visible";
    });

    // This function will be called if the reward is granted
    function addCreditsToAccount() {
        console.log("Credits added to account");
    }
</script>
```

--------------------------------

### Display More Ads for New Content

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Call `ezstandalone.displayMore()` when new placeholders are added to the page after initial load, such as through scrolling. This fetches ad codes for these new placeholders.

```javascript
window.ezstandalone.cmd.push(function() {
    // call new placeholders
    ezstandalone.displayMore(104, 105);
});
```

--------------------------------

### Automate Ads.txt Updates

Source: https://docs.ezoic.com/docs/ezoicads/adstxt

Use a curl command to fetch the latest ads.txt file. This is intended for use in a daily cron job.

```bash
curl -L https://srv.adstxtmanager.com/19390/[YOUR_DOMAIN].com > ads.txt
```

--------------------------------

### Constructing a UTM-tagged URL with zid

Source: https://docs.ezoic.com/docs/identity/integrations/beehiiv

Append the BeeHiiv dynamic zid parameter to your newsletter links to enable first-party data tracking.

```text
https://www.content-website.com/page?utm_content=zid-{{zid}}
```

--------------------------------

### Reuse placeholders for infinite scroll

Source: https://docs.ezoic.com/docs/ezoic-legacy-features/legacy

Destroy existing placeholders and re-display them to refresh ads as the user continues scrolling.

```html
<script>
    window.ezstandalone.cmd.push(function() {
        // destroy initial place
        ezstandalone.destroyPlaceholders(102,103,104);
        // call new placeholders
        ezstandalone.displayMore(102,103,104);
    });
</script>
```

--------------------------------

### Request and Show Rewarded Ad

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Use this method to request and display a rewarded ad. The callback function handles the result status and reward logic.

```javascript
window.ezRewardedAds.cmd.push(() => {
    window.ezRewardedAds.requestAndShow(
        (result) => { // Callback function
            if (result.status) {
                if (result.reward) {
                    console.log("Reward granted!");
                } else {
                    console.log("User closed the ad early, no reward granted.");
                }
            } else {
                console.log("Rewarded ad request failed:", result.msg);
            }
        },
        { // Config object
            rewardName: "Main Page Credits Reward",
            alwaysCallback: true,
            rewardOnNoFill: false
        }
    );
});
```

--------------------------------

### Add Ezoic Privacy Scripts

Source: https://docs.ezoic.com/docs/ezoicads/integration

Load these scripts at the top of the <head> tag to manage user consent. The data-cfasync="false" attribute is required to prevent Cloudflare optimization conflicts.

```html
<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 Command Queue Helper Function

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/nextjs

Create a `runEzoic` helper function in `lib/ezoic.ts` to safely push functions to the Ezoic command queue. This prevents errors by ensuring the `ezstandalone` object and its `cmd` array exist before attempting to push.

```typescript
export function runEzoic(fn: () => void) {
    if (typeof window === "undefined") return;
    window.ezstandalone = window.ezstandalone || {};
    window.ezstandalone.cmd = window.ezstandalone.cmd || [];
    window.ezstandalone.cmd.push(fn);
}

```

--------------------------------

### Integrate Content Locker with HTML Elements

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Trigger the content locker via a button click with a fallback mechanism if ads are unavailable.

```html
<button onclick="unlockContent()">Access Premium Content</button>

<script>
    function unlockContent() {
        if (window.ezRewardedAds && window.ezRewardedAds.ready) {
            window.ezRewardedAds.contentLocker(
                "https://example.com/premium-content",
                {
                    callToAction: {
                        header: "Access Premium Content",
                        body: "Watch a short ad to continue"
                    }
                }
            );
        } else {
            // Fallback if rewarded ads aren't available
            window.location.href = "https://example.com/premium-content";
        }
    }
</script>
```

--------------------------------

### POST /gateway/bdaservices/getCustomData/

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

Retrieves custom rewarded ad data based on specified dimensions, metrics, and filters.

```APIDOC
## POST /gateway/bdaservices/getCustomData/

### Description
Retrieves custom data for rewarded ads, allowing filtering by reward ID and specifying desired dimensions and metrics.

### Method
POST

### Endpoint
https://api-gateway.ezoic.com/gateway/bdaservices/getCustomData/

### Parameters
#### Query Parameters
- **developerKey** (string) - Required - Your unique API developer key found in the publisher dashboard.

#### Request Body
- **StartDate** (string) - Required - Start date for the data range (YYYY-MM-DD).
- **EndDate** (string) - Required - End date for the data range (YYYY-MM-DD).
- **Platform** (string) - Required - The platform to query (e.g., "ALL").
- **DomainId** (number) - Required - The unique ID for your domain.
- **DimensionColumns** (array) - Required - List of dimensions to retrieve (e.g., reward_id, reward_status, is_matched).
- **MetricColumns** (array) - Required - List of metrics to retrieve (e.g., reward_revenue).
- **Order** (object) - Optional - Sorting configuration for the results.
- **Filters** (array) - Optional - Filtering criteria for the query.

### Request Example
{
	"StartDate": "2025-08-12",
	"EndDate": "2025-08-13",
	"Platform": "ALL",
	"DomainId": 12345,
	"DimensionColumns": [
        { "Data": "reward_id", "Type": "string" },
        { "Data": "reward_status", "Type": "string" },
        { "Data": "is_matched", "Type": "number" }
    ],
    "MetricColumns":[
        { "Data": "reward_revenue", "Type": "number" }
    ],
    "Order": { "ColumnNumber": 0, "Direction": "DESC" },
    "Filters": [
        { "Type": "INCLUDE", "FilterKey": "reward_id", "OperationId": "EXACTLY", "FilterValue": "YOUR_REWARD_ID" }
    ]
}

### Response
#### Success Response (200)
- **Message** (string) - Status message.
- **Success** (boolean) - Indicates if the request was successful.
- **Data** (array) - List of rewarded ad records.

#### Response Example
{
  "Message": "",
  "Success": true,
  "Data": [
    {
      "is_matched": "1",
      "reward_id": "YOUR_REWARD_ID",
      "reward_revenue": "$0.00",
      "reward_status": "not completed"
    }
  ]
}
```

--------------------------------

### Insert Ezoic Ad Placeholder

Source: https://docs.ezoic.com/docs/ezoicads/implementation

Place this HTML and script block at each location where an ad should appear. Replace the placeholder ID with your specific ID from the Ezoic dashboard.

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

--------------------------------

### Minimal Javascript Integration for Rewarded Ads

Source: https://docs.ezoic.com/docs/ezoicadsadvanced/rewarded

This is the minimal integration required to load rewarded ads code if the page does not already have ads. It includes consent management and Ezoic's standalone script.

```html
<script data-cfasync="false" src="https://the.gatekeeperconsent.com/cmp.min.js"></script>
<script src="https://the.gatekeeperconsent.com/ccpa/v2/standalone.js" async></script>

<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>

<script>
    window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(() => {
        ezstandalone.initRewardedAds();
    });
</script>

<script>
    window.ezRewardedAds = window.ezRewardedAds || {};
    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
</script>
```
Tokens:
Raw