Rewarded Ads

Rewarded ads are a type of ad that allows users to view an ad for a minimum amount of time in exchange for a reward.

Rewarded ads fill the entire display, similar to how interstitial ads are displayed. Two key differences are that video ads can be displayed in addition to banner ads, and there is a timer that must be completed before the reward is granted. The time remaining is displayed to the user as it counts down.

The user can close the ad at any time, but if it is closed before the timer is up, the reward will not be granted. The user will be prompted to confirm that they want to close the ad early and forfeit the reward.

The ad remains on screen after the timer has expired, at which point the user can close the ad without forfeiting the reward.

Integration 🔗

We provide an interface for requesting and displaying the ads (detailed below), and we notify your code when the ad window is closed, and whether the reward was granted, through a callback.

You are responsible for integrating the rewards into your app. This includes asking the user if they want to view the ad, and handling the reward when it is granted.

Rewarded ads can be requested to be shown at any time. After requesting, there will be a short delay (1-2 seconds) while we fetch an ad before it is ready to be shown.

You must always ask the user if they want to view the ad before showing it, and you cannot mislead or incentivize the user to view the ad.

Reward Restrictions 🔗

You are free to choose the reward that you offer to the user. However, there are some restrictions on what you can offer:

  1. The reward may not be a direct monetary item under any circumstance. Examples include cash, cryptocurrency, or gift cards.

  2. The reward may be an indirect monetary item, as long as it is non-transferrable, and only redeemable within your platform, website, or app.

    • Indirect monetary items are items with monetary value that aren't a direct form of payment in the real world. If the reward is a discount or voucher for a physical item, they must not exceed 25% of the item's value.

    • Examples of indirect monetary items include discounts, loyalty rewards or points, product free shipping, product or service free trials, game character extra lives, and game character skins.

  3. Random rewards are allowed with some restrictions:

    • You must disclose the odds of receiving each reward before the user agrees to view the ad.

    • Details on all rewards must be easily accessible to the user.

    • The odds of receiving any reward must be greater than zero.

  4. More than one rewarded ad can be required to be watched back-to-back for one reward, but this must be clearly disclosed to the user before they accept to watch the ads.

You can read more about Google's rewarded ad policies here: https://support.google.com/admanager/answer/7496282

Initialization 🔗

The following code must be included before any other rewarded ad functions are called, no matter what integration type you are using. Ideally, this code should be included in the <head> of your page, or at least at the top of the <body>.

1window.ezRewardedAds = window.ezRewardedAds || {};
2window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];

Javascript Integration 🔗

If you are integrated with Javascript, the page must have the ezstandalone initialization, as well as at least one showAds() call. If the page does not already call showAds(), you can use showAds(12) to load only the rewarded ads code. Note that this will not request a rewarded ad, that must be done separately.

If you already have ads on the page, you only need the ezRewardedAds initialization code.

1<script>
2    window.ezRewardedAds = window.ezRewardedAds || {};
3    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
4</script>

If the page does not already have ads, the following code is the minimal integration required to load the rewarded ads code:

(Note that if you have anchor or video ads enabled site-wide, those will load automatically as well. If you only want rewarded ads, you will need to add page rules to disable those ad types.)

 1<script src="https://the.gatekeeperconsent.com/cmp.min.js" data-cfasync="false"></script>
 2<script src="https://the.gatekeeperconsent.com/ccpa/v2/standalone.js" async></script>
 3
 4<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
 5
 6<script>
 7    window.ezstandalone = window.ezstandalone || {};
 8    ezstandalone.cmd = ezstandalone.cmd || [];
 9    ezstandalone.cmd.push(function () {
10        ezstandalone.showAds(12);
11    });
12</script>
13
14<script>
15    window.ezRewardedAds = window.ezRewardedAds || {};
16    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
17</script>

Cloud Integration 🔗

If you are cloud integrated, then the rewarded ads code will be loaded automatically when the page loads.

In this case, the initialization code is simply:

1<script>
2    window.ezRewardedAds = window.ezRewardedAds || {};
3    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
4</script>

Checking if the code is loaded 🔗

The rewarded ads code will not be ready immediately after the page loads, although the delay is quite short, around 1-2 seconds on most connections.

You should also consider that the code may not ever be loaded in some situations, such as if the network request fails, or if the user is using a browser that is blocking ad code.

There are two ways to ensure that the code is loaded before calling any of the functions:

  1. Checking the ezRewardedAds.ready property:

    You can check if the ezRewardedAds object is ready by checking the ready property. This property will be true once the code is loaded.

    This is useful when you have a specific moment in time that you want to display a rewarded ad, such as at the end of a level in a game, or when the user clicks a button. This also ensures that you are only interrupting user interaction when the rewarded ad code is ready to be used.

    If you are using this method, you don't need to use the cmd queue.

    1if (window.ezRewardedAds.ready) {
2    // Your code here
3} else {
4    // The code is not ready yet
5}

  2. Using the cmd queue:

    The cmd queue is a list of functions that will be called as soon as the rewarded ads code is ready.

    This method is useful if you would like to show a rewarded ad as soon as possible after the page loads.

    You can also use the cmd queue to call your own functions once the code is loaded, such as displaying a button to request a rewarded ad.

    Keep in mind that if the rewarded ad code fails to load, the functions in the cmd queue will not be called.

    1window.ezRewardedAds.cmd.push(function () {
2    // Your code here
3});

Quick Start 🔗

Javascript Integration 🔗

The following example shows how to load the rewarded ads code and display a button that will request a rewarded ad when clicked. The button will only be displayed once the code is loaded.

 1<script src="https://the.gatekeeperconsent.com/cmp.min.js" data-cfasync="false"></script>
 2<script src="https://the.gatekeeperconsent.com/ccpa/v2/standalone.js" async></script>
 3<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
 4<script>
 5    window.ezstandalone = window.ezstandalone || {};
 6    ezstandalone.cmd = ezstandalone.cmd || [];
 7    ezstandalone.cmd.push(function () {
 8        ezstandalone.showAds(12);
 9    });
10
11    window.ezRewardedAds = window.ezRewardedAds || {};
12    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
13</script>
14
15<button 
16    id="rewardedAdButton" 
17    style="visibility:hidden;" 
18    onclick="window.ezRewardedAds.requestWithOverlay(addCreditsToAccount, {body: ['You will receive 10 credits for watching this ad.']})">
19    Watch Ad for 10 Credits
20</button>
21
22<script>
23    // Show the button when the rewarded ad code is ready
24    window.ezRewardedAds.cmd.push(function () {
25        document.getElementById("rewardedAdButton").style.visibility = "visible";
26    });
27
28    // This function will be called if the reward is granted
29    function addCreditsToAccount() {
30        console.log("Credits added to account");
31    }
32</script>

Cloud Integration 🔗

This is the same example as above, but without the ezstandalone code. The rewarded ads code will be loaded automatically when the page loads.

 1<script>
 2    window.ezRewardedAds = window.ezRewardedAds || {};
 3    window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
 4</script>
 5
 6<button 
 7    id="rewardedAdButton" 
 8    style="visibility:hidden;" 
 9    onclick="window.ezRewardedAds.requestWithOverlay(addCreditsToAccount, {body: ['You will receive 10 credits for watching this ad.']})">
10    Watch Ad for 10 Credits
11</button>
12
13<script>
14    // Show the button when the rewarded ad code is ready
15    window.ezRewardedAds.cmd.push(function () {
16        document.getElementById("rewardedAdButton").style.visibility = "visible";
17    });
18
19    // This function will be called if the reward is granted
20    function addCreditsToAccount() {
21        console.log("Credits added to account");
22    }
23</script>

Usage 🔗

requestWithOverlay() 🔗

This method requests a rewarded ad and displays an overlay to the user asking if they want to view the ad. It provides several options for customizing the overlay, including the title, message, and button text. It also provides options for adjusting the overlay and reward behavior.

Parameters 🔗

  • callback (Function): A function executed when the ad request completes. The function receives a single result object with the following properties:
    • status (Boolean):
      • true if the ad loaded and the user had a chance to be able to view the ad.
      • false if an error occurred or if the ad went unfilled.
    • reward (Boolean): Whether the reward was granted.
    • msg (String): A message detailing the outcome (e.g., "ad ready" or an error message).
    • 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.
  • text (Object): An object containing the text to display in the overlay. The object can contain the following properties:
    • header (String, optional): The title of the overlay. Default is "Watch Ad to Continue?".
    • body (String Array, optional): The message to display in the overlay. Each array entry is one line. Default is no body text.
    • accept (String, optional): The text for the 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 overlay. The object can contain the following properties:
    • rewardName (String, optional): The name of the rewarded ad to identify usage or location 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 overlay is displayed. This is useful if you are gating content behind a reward. Default is false.
    • rewardOnNoFill (Boolean, optional): Whether to grant the reward in the event that an ad does not fill, or there is an internal error. Useful when combined with alwaysCallback = false and you don't want to prevent a user action if an ad cannot be shown. The reward will not be granted if the user declines to watch the ad, or if they close the ad early. Default is false.

Usage Examples 🔗

Basic Example 🔗

This example shows the most basic usage. All default values are used, and we don't need to check the reward outcome, since alwaysCallback is set to false by default.

All we need to set is

  • The callback function, which is the action that will be taken if and only if the reward is granted
  • The body text, which we need to set to inform the user of what the reward is for.
1window.ezRewardedAds.cmd.push(function () {
2    window.ezRewardedAds.requestWithOverlay(grantReward, {body: ['You will get a reward for watching this ad.']});
3});
4function grantReward() {
5    console.log("Reward granted!");
6}
Replacing a button event 🔗

This example sets rewardOnNoFill to true, which means that callback will still be called even if an ad cannot be found, or if there is another error.

This is useful if you want to replace a button event with a rewarded ad, but you don't want to prevent the user from taking the action if an ad cannot be found.

This also checks if the rewarded ads code has loaded, and if it hasn't, it will call the takePremiumAction() function directly.

 1<button id="premiumActionButton" onclick="takePremiumActionWithAd()">Take Premium Action</button>
 2
 3<script>
 4    function takePremiumActionWithAd() {
 5        if (window.ezRewardedAds.ready) {
 6            window.ezRewardedAds.requestWithOverlay(
 7                takePremiumAction,
 8                {body: ['You will be able to take the premium action after watching an ad.']},
 9                {rewardOnNoFill: true}
10            );
11        } else {
12            takePremiumAction();
13        }
14    }
15    function takePremiumAction() {
16        console.log("Premium action taken!");
17    }
18</script>
Using alwaysCallback 🔗

This example sets alwaysCallback to true, which means that the callback will be called even if the reward is not granted.

This allows you to handle the case where the user declines to watch the ad, or if an ad cannot be found.

This is useful if you want to take an action regardless of whether the ad was shown or not.

This example also demonstrates how to use an anonymous function as the callback (function (result) {handleRewardResult(result);}) to allow for the result parameter to be passed to another function, in this case handleRewardResult.

 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.requestWithOverlay(
 3        function (result) {handleRewardResult(result);},
 4        {body: ["You will receive 10 credits for watching this ad."]}, 
 5        {alwaysCallback: true}
 6    );
 7});
 8
 9function handleRewardResult(result) {
10    if (result.status) {
11        if (result.reward) {
12            takePremiumAction();
13        } else {
14            displayMessageToUser("Sorry, you did not receive a reward.");
15        }
16    } else {
17        displayMessageToUser("Sorry, there was an error loading the ad.");
18        // 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.
19    }
20}
21
22function takePremiumAction() {
23    console.log("Premium action taken!");
24}
25
26function displayMessageToUser(message) {
27    console.log(message);
28}
Full Example 🔗

This example uses all available options, and serves mostly as a reference to copy-paste from.

 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.requestWithOverlay(
 3        function(result) { // Callback function
 4            if (result.status) {
 5                if (result.reward) {
 6                    console.log("Reward granted!");
 7                } else {
 8                    console.log("User either declined to watch the ad, or they closed the ad early.");
 9                }
10            } else {
11                console.log("Rewarded ad request failed:", result.msg);
12            }
13        }, 
14        { // Text object
15            header: "Watch Ad to Continue?",
16            body: ["You will receive 10 credits for watching this ad.", "Click the button below to watch the ad."],
17            accept: "Watch ad",
18            cancel: "Cancel"
19        }, 
20        { // Config object
21            alwaysCallback: true,
22            lockScroll: true,
23            rewardOnNoFill: false
24        }
25    );
26});

Advanced Usage 🔗

These functions allow for direct access to the two stages of rewarded ads: requesting and showing the ad.

You can use these functions to create your own custom overlay or UI for asking the user if they want to view the ad, or if you want to integrate the ad more directly into your site, for example a button in a game.

Keep in mind that you are still required to ask the user in some way whether they want to view the ad.

request() 🔗

This method requests a rewarded ad. It takes a callback function as a parameter, which is called once the ad is ready, if the ad went unfilled, or if an error occurs.

  • request() can be called:

    • even if show() was never called (e.g., if the user declined to view the ad). After calling request() again, show() can then be called as normal.
    • before the Ezoic rewarded ads code loads. It will be queued and executed once the code is loaded (this is the purpose of window.ezRewardedAds.cmd.push() in the example). There should only be a very brief delay between the page loading (or, in the case of a standalone integration, the first call to ezstandalone.showAds()) and the rewarded ad code loading.

  • once request() has been called, it cannot be called:

    • until the callback is called. Only one request can be made at a time.
    • while an ad is already showing (ie. after show() is called but before the ad window is closed).

Parameters 🔗

  • callback (Function): A function executed when the ad request completes. The function receives a single result object with the following properties:
    • status (Boolean):
      • true if the ad is ready.
      • false if an error occurred or if the ad went unfilled.
    • msg (String): A message detailing the outcome (e.g., "ad ready" or an error message).
    • 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.

Usage Example 🔗 

 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.request(function(result) {
 3        if (result.status) {
 4            console.log("Rewarded ad is ready");
 5            // Ask the user if they want to view the ad
 6        } else {
 7            console.log("Rewarded ad request failed:", result.msg);
 8        }
 9    });
10});

show() 🔗

This method displays the rewarded ad that was loaded using request(). It takes one parameter: a callback function that is called when the ad is closed and indicates whether the reward was granted.

Parameters 🔗

  • callback (Function): 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 (e.g., if the ad was not ready or if there was an internal error).
    • reward (Boolean): Whether the reward was granted.
    • msg (String): A message detailing the outcome (e.g., "ad closed" or an error message).
    • 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. The object can contain the following properties:
    • rewardName (String, optional): The name of the rewarded ad to identify usage or location for analytics. Accepts alphanumeric characters, spaces, and some punctuation. Default is "".

Usage Example:

 1window.ezRewardedAds.show(function (closeResult) {
 2    if (closeResult.status) {
 3        console.log("Rewarded ad closed");
 4        if (closeResult.reward) {
 5            console.log("Reward granted!");
 6        }
 7    } else {
 8        console.log("Failed to show rewarded ad:" + closeResult.msg);
 9    }
10});

Complete Advanced Usage Example 🔗

Below is a full example demonstrating how to request and show a rewarded ad, including prompting the user to confirm ad viewing

The example uses the built-in confirm() function to ask the user if they want to view the ad. This is just an example, and you can use any method you like to ask the user if they want to view the ad.

The example uses console logging to indicate the status of the ad and whether the reward was granted. You can replace this with your own code to handle the various outcomes.

 1// Ensure the global object is initialized
 2window.ezRewardedAds = window.ezRewardedAds || {};
 3window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
 4
 5window.ezRewardedAds.cmd.push(function () { // Queue a command to request and show a rewarded ad
 6    window.ezRewardedAds.request(function (requestResult) { // Request a rewarded ad
 7        if (requestResult.status) {
 8            if (confirm("Watch ad for reward?")) { // Ask the user if they want to watch the ad for a reward
 9                window.ezRewardedAds.show(function (closeResult) {
10                    if (closeResult.status) {
11                        console.log("Rewarded ad closed");
12                        if (closeResult.reward) {
13                            console.log("Reward granted!");
14                        }
15                    } else {
16                        console.log("Failed to show rewarded ad:" + closeResult.msg);
17                    }
18                });
19            } else {
20                // User declined to watch the ad
21            }
22        } else {
23            console.log("Rewarded ad request failed:", requestResult.msg);
24        }
25    });
26});

Note that the call to show() does not need to be inside the request() callback. You can call show() at any time after the callback provided to request() has been called and result.status is true:

 1// Ensure the global object is initialized
 2window.ezRewardedAds = window.ezRewardedAds || {};
 3window.ezRewardedAds.cmd = window.ezRewardedAds.cmd || [];
 4
 5// Request a rewarded ad
 6window.ezRewardedAds.cmd.push(function () {
 7    window.ezRewardedAds.request(function (requestResult) {
 8        if (requestResult.status) {
 9            // Ask the user if they want to view the ad. For example, display a button that calls showRewardedAd() when clicked
10        } else {
11            console.log("Rewarded ad request failed:", requestResult.msg);
12        }
13    });
14});
15
16function showRewardedAd() {    
17    window.ezRewardedAds.show(function (closeResult) {
18        if (closeResult.status) {
19            console.log("Rewarded ad closed");
20            if (closeResult.reward) {
21                console.log("Reward granted!");
22            }
23        } else {
24            console.log("Failed to show rewarded ad:" + closeResult.msg);
25        }
26    });
27}

Error Handling & Considerations 🔗

  • Single Request at a Time:
    If an ad is already loading, subsequent calls to request() or requestWithOverlay() will trigger an error callback (result.status = false). Wait for the current ad load to complete before calling request() again.

  • Ad Readiness:
    Calling show() when no ad is ready will result in an error callback (result.status = false) with a message like "rewarded ad not ready. call request() first".

  • Valid Callbacks:
    Always pass a valid function to the callback argument to all methods. If an argument is not provided, or if the provided argument is not a function, a warning is logged and no further action will be taken.

Specialized Rewarded Ad Types 🔗

Content Locker 🔗

Content Locker is a specialized implementation of rewarded ads that gates specific content or actions behind ad viewing. It automatically selects the highest revenue ad format from multiple types (rewarded video, interstitial, or outstream video ads) to maximize revenue while providing a seamless user experience.

Key Features 🔗

  • Multi-format competition: Automatically competes rewarded video ads against interstitial and outstream video ads, selecting the format with the highest CPM
  • Smart fallbacks: If the primary rewarded ad doesn't fill, it intelligently falls back to alternative ad formats
  • Flexible actions: Supports both URL redirects and callback functions as the gated action
  • Loading states: Optional loading overlay to improve user experience during ad loading
  • Customizable UI: Configurable call-to-action text and styling

Usage 🔗

The Content Locker is accessed via the contentLocker() method:

1window.ezRewardedAds.contentLocker(action, config)

Parameters 🔗

  • action (String or Function): The action to gate behind the ad
    • If a string, it will be treated as a URL to redirect to after the ad
    • If a function, it will be called after the ad is completed
  • config (Object, optional): Configuration options for the content locker

Configuration Options 🔗

  • loadingOverlay (Boolean, optional): Whether to show a loading overlay while the ad loads. Default is true.
  • readyCallback (Function, optional): Called when the ad is ready to show (before display). Default is null.
  • rewardName (String, optional): The name of the rewarded ad to identify usage or location for analytics. Accepts alphanumeric characters, spaces, and some punctuation. Default is "".
  • callToAction (Object, optional): Customizes the call-to-action overlay text:
    • disabled (Boolean): If true, skips the overlay and shows the ad immediately. Default is false.
    • header (String): Header text for the overlay. Default is "Before Continuing".
    • body (String): Body text for the overlay. Default is "Please watch a short ad from our sponsors".
    • button (String): Button text for the overlay. Default is "Watch Ad and Continue →".

Basic Examples 🔗

URL Redirect 🔗

Gate a URL redirect behind an ad:

1window.ezRewardedAds.cmd.push(function () {
2    window.ezRewardedAds.contentLocker("https://example.com/premium-content");
3});
Function Callback 🔗

Gate a function call behind an ad:

 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.contentLocker(function() {
 3        console.log("Premium action executed!");
 4        unlockPremiumFeature();
 5    });
 6});
 7
 8function unlockPremiumFeature() {
 9    // Your premium feature code here
10}

Advanced Examples 🔗

Custom Call-to-Action Text 🔗 
 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.contentLocker(
 3        "https://example.com/premium-content",
 4        {
 5            callToAction: {
 6                header: "Unlock Premium Content",
 7                body: "Watch a quick ad to access exclusive content",
 8                button: "Unlock Content"
 9            }
10        }
11    );
12});
With Loading Overlay and Ready Callback 🔗 
 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.contentLocker(
 3        function() { 
 4            downloadFile(); 
 5        },
 6        {
 7            loadingOverlay: true,
 8            readyCallback: function(result) {
 9                console.log("Ad ready status:", result.status);
10            },
11            callToAction: {
12                header: "Download Premium File",
13                body: "Support our site by watching a short ad",
14                button: "Start Download"
15            }
16        }
17    );
18});
Skip Overlay (Direct Ad Display) 🔗

For cases where you want to show the ad immediately without asking:

 1window.ezRewardedAds.cmd.push(function () {
 2    window.ezRewardedAds.contentLocker(
 3        "https://example.com/download",
 4        {
 5            callToAction: {
 6                disabled: true  // Skip the overlay, show ad immediately
 7            }
 8        }
 9    );
10});

Integration with HTML Elements 🔗

Content Locker can be easily integrated with buttons or links:

 1<button onclick="unlockContent()">Access Premium Content</button>
 2
 3<script>
 4    function unlockContent() {
 5        if (window.ezRewardedAds && window.ezRewardedAds.ready) {
 6            window.ezRewardedAds.contentLocker(
 7                "https://example.com/premium-content",
 8                {
 9                    callToAction: {
10                        header: "Access Premium Content",
11                        body: "Watch a short ad to continue"
12                    }
13                }
14            );
15        } else {
16            // Fallback if rewarded ads aren't available
17            window.location.href = "https://example.com/premium-content";
18        }
19    }
20</script>