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:

The reward may not be a direct monetary item under any circumstance. Examples include cash, cryptocurrency, or gift cards.
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.
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.
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:

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}
```
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).
text (Object): An object containing the text to display in the overlay. The object can contain the following properties:
- title (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:
- 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            title: "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).

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

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.
tag (String, optional): A tracking tag for analytics purposes. 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>

How It Works 🔗

Ad Competition: When called, Content Locker requests bids from multiple ad formats (rewarded video, interstitial, outstream video)
Format Selection: It automatically selects the ad format with the highest CPM to maximize revenue
User Experience:
- Shows a customizable overlay asking the user to watch an ad
- If the user accepts, displays the winning ad format
- After successful ad completion, executes the gated action
Fallback Handling: If the primary ad format fails, it falls back to alternative formats with a countdown timer

Best Practices 🔗

Clear Value Proposition: Make it clear what the user will receive after watching the ad
Appropriate Gating: Only gate content that provides clear value to justify the ad viewing
Fallback Handling: Always provide a way for users to access content even if ads fail to load
Testing: Test the integration to ensure it works properly when ads don't fill

Technical Notes 🔗

Content Locker automatically handles ad refresh prevention to avoid conflicts
Uses aggressive floor pricing (starting at 20 cents CPM) to maximize revenue
Supports up to 2 retries if the initial ad request doesn't fill
Automatically tracks analytics events for revenue optimization

Offerwall 🔗

Offerwall is a site-wide rewarded ad system that blocks users from continuing to browse after a certain number of pageviews, requiring them to watch a rewarded ad to continue. This creates a sustainable revenue model by ensuring frequent users contribute to site monetization while maintaining a good user experience with configurable cooldown periods.

Key Features 🔗

Pageview-based triggering: Automatically shows after a configurable number of unique page visits
Smart cooldown system: Prevents ad fatigue with configurable time delays between shows
Cookie-based tracking: Tracks pageviews and cooldown status across browsing sessions
A/B testing built-in: Includes holdout group functionality for measuring revenue impact
URL exclusions: Supports excluding specific pages or directories from offerwall logic
Customizable messaging: Full control over modal text, buttons, and styling
Revenue attribution: Automatic GAM targeting for proper revenue tracking

How It Works 🔗

Pageview Tracking: Tracks unique URLs visited by the user using cookies
Threshold Check: When the configured minimum pageviews is reached, triggers the offerwall
Modal Display: Shows a blocking modal requiring ad viewing to continue
Cooldown Management: After successful ad completion, sets a cooldown period
A/B Testing: Randomly assigns users to test/control groups for impact measurement

Configuration 🔗

The Offerwall system is typically configured server-side through your Ezoic dashboard, but the core configuration options include:

minPageviews (Number): Minimum pageviews before showing offerwall. Default is 3. Set to 0 to show on landing page.
cooldown (Number): Hours to wait before showing again after successful completion. Default is 1.0.
sampleRate (Number): Percentage of users to exclude from offerwall for A/B testing (0.0 to 1.0). Default is 0.05 (5%).
urlDirExcludes (Array): Directory paths to exclude from offerwall logic (e.g., ["/admin", "/checkout"]).
urlPathExcludes (Array): Exact page paths to exclude from offerwall logic (e.g., ["/contact", "/privacy"]).

Text Customization 🔗

header (String): Modal header text. Default is "Watch Ad to Continue Browsing".
body (Array): Modal body text lines. Can include multiple paragraphs.
acceptText (String): Accept button text. Default is "Watch Ad".
cooldownMessage (String): Template for cooldown message with %cooldown placeholder.
logoImageUrl (String): URL for logo image in modal header.

Styling Options 🔗

acceptButtonBackgroundColor (String): CSS color for the accept button background.
acceptButtonTextColor (String): CSS color for the accept button text.

Usage Examples 🔗

Basic Implementation 🔗

The Offerwall typically runs automatically when configured through your Ezoic dashboard. However, you can access the underlying functionality:

1// The offerwall runs automatically based on pageview tracking
2// No direct API calls needed for standard implementation

Checking Offerwall Status 🔗

You can check if the offerwall is currently in cooldown:

1// Check if user is in cooldown period
2function isOfferwallActive() {
3    // This would typically be handled by the Ezoic system
4    // but you can check cookie status if needed
5    const cookies = document.cookie.split(';');
6    return cookies.some(cookie => cookie.trim().startsWith('ezorwadbl='));
7}

Custom URL Exclusions 🔗

If you need to programmatically exclude certain pages:

 1// Example of URL patterns that would be excluded
 2const excludedPaths = [
 3    "/admin",           // Admin pages
 4    "/checkout",        // E-commerce checkout flow  
 5    "/payment",         // Payment pages
 6    "/login",           // Authentication pages
 7    "/api"              // API endpoints
 8];
 9
10// Example of directory exclusions
11const excludedDirectories = [
12    "/user",            // User dashboard area
13    "/account",         // Account management
14    "/help"             // Help/support section
15];

Integration Considerations 🔗

E-commerce Sites 🔗

For e-commerce sites, it's crucial to exclude checkout and payment flows:

 1// Recommended exclusions for e-commerce
 2const ecommerceExclusions = {
 3    urlPathExcludes: [
 4        "/cart",
 5        "/checkout", 
 6        "/payment",
 7        "/order-confirmation"
 8    ],
 9    urlDirExcludes: [
10        "/account",
11        "/admin"
12    ]
13};

Content Sites 🔗

For content sites, you might want to exclude certain critical pages:

 1// Recommended exclusions for content sites
 2const contentSiteExclusions = {
 3    urlPathExcludes: [
 4        "/contact",
 5        "/privacy", 
 6        "/terms",
 7        "/subscribe"
 8    ],
 9    urlDirExcludes: [
10        "/legal"
11    ]
12};

Revenue Optimization 🔗

The Offerwall system automatically optimizes for revenue through:

A/B Testing: Built-in holdout groups to measure incremental revenue
GAM Targeting: Automatic targeting parameter (offerwall-shown) for revenue attribution
Smart Timing: Pageview-based triggering ensures users are engaged before showing ads
Cooldown Management: Prevents ad fatigue while maximizing long-term revenue

Analytics and Tracking 🔗

The system automatically tracks:

Pageview counts: Unique page visits per user
Offerwall displays: When and how often users see the offerwall
Completion rates: How often users complete the ad vs. abandon
Revenue attribution: GAM targeting for proper revenue tracking
A/B test assignment: Control group tracking for impact measurement

Best Practices 🔗

Appropriate Thresholds: Set minPageviews high enough to capture engaged users (3-5 pageviews recommended)
Reasonable Cooldowns: Balance revenue with user experience (1-4 hours typical)
Strategic Exclusions: Exclude critical user flows like checkout, login, and contact pages
Clear Messaging: Use friendly, value-focused messaging explaining the "why" behind the ad
Monitor Performance: Use A/B testing to optimize thresholds and messaging
Mobile Optimization: Ensure modal text and buttons work well on mobile devices

Technical Implementation 🔗

The Offerwall system integrates with the existing rewarded ad infrastructure:

1// Offerwall uses the same underlying ad system
2__ez.fads.adLoadRewarded.requestAndShowOverlay(
3    callback,           // Success callback
4    textConfig,         // Modal text configuration  
5    behaviorConfig      // Modal behavior (non-cancellable, scroll-locked)
6);

Troubleshooting 🔗

Common Issues:

Offerwall not showing: Check URL exclusions and pageview count
Too frequent display: Verify cooldown configuration and cookie persistence
User complaints: Adjust threshold or improve messaging
Revenue impact: Review A/B test results and optimize timing

Debug Information:

The system logs detailed information to browser console when debugging is enabled:

Pageview tracking and counting
URL exclusion checks
Cookie management
A/B test assignment
Offerwall trigger decisions

Migration and Setup 🔗

When implementing Offerwall:

Start Conservative: Begin with higher pageview thresholds (5+) and longer cooldowns (4+ hours)
Monitor Metrics: Watch bounce rates, session duration, and user feedback
Iterate Based on Data: Adjust thresholds based on A/B test results
Exclude Critical Flows: Ensure checkout, signup, and other conversion paths are excluded
Test Thoroughly: Verify functionality across different user journeys and devices