New Features (Beta)

Overview

These are new features that are available to be implemented but are still in Beta and may change before being fully released.

ShowAds

Basic Usage

showAds is a new function in ezstandalone that allows for calling for placeholders. The basic usage of ezstandalone.showAds involves passing a single placeholder ID or an array of placeholder IDs to the function. Below is an example of how placeholders are currently called, followed by how they can now be called

Current:

1<script>
2    window.ezstandalone = window.ezstandalone || {};
3    ezstandalone.cmd = ezstandalone.cmd || [];
4    ezstandalone.cmd.push(function() {
5        ezstandalone.define(102,103,104);
6        ezstandalone.enable();
7        ezstandalone.display();
8    });
9</script>

New:

1<script>
2    window.ezstandalone = window.ezstandalone || {};
3    ezstandalone.cmd = ezstandalone.cmd || [];
4    ezstandalone.cmd.push(function() {
5        ezstandalone.showAds(102,103,104);
6    });
7</script>

Not only does it reduce the amount of functions, it also removes the complexity of using define/enable/display with displayMore for dynamic content. Below is an example of how someone might implement a page with dynamically loaded pages, followed by how it can be implemented with showAds

Current:

 1<body>
 2    <!-- static content + placeholders -->
 3    <div class="content1">
 4        <div id="ezoic-pub-ad-placeholder-101"></div>
 5    </div>
 6    <div class="content2">
 7        <div id="ezoic-pub-ad-placeholder-102"></div>
 8    </div>
 9    <div class="content3">
10        <div id="ezoic-pub-ad-placeholder-103"></div>
11    </div>
12    <script>
13        window.ezstandalone = window.ezstandalone || {};
14        ezstandalone.cmd = ezstandalone.cmd || [];
15        ezstandalone.cmd.push(function() {
16            ezstandalone.define(102, 103, 104);
17            ezstandalone.enable();
18            ezstandalone.display();
19        });
20    </script>
21
22    ...
23
24    <!-- dynamic content + placeholders -->
25    <div class="dynamic content1">
26        <div id="ezoic-pub-ad-placeholder-104"></div>
27        <script>
28            ezstandalone.cmd.push(function() {
29                ezstandalone.displayMore(104)
30            });
31        </script>
32    </div>
33    <div class="dynamic content2">
34        <div id="ezoic-pub-ad-placeholder-105"></div>
35        <script>
36            ezstandalone.cmd.push(function() {
37                ezstandalone.displayMore(105)
38            });
39        </script>
40    </div>
41</body>

New:

 1<body>
 2    <script>
 3        window.ezstandalone = window.ezstandalone || {};
 4        ezstandalone.cmd = ezstandalone.cmd || [];
 5    </script>
 6    <!-- static content + placeholders -->
 7    <div class="content1">
 8        <div id="ezoic-pub-ad-placeholder-101"></div>
 9        <script>
10            ezstandalone.cmd.push(function() {
11                ezstandalone.showAds(101)
12            });
13        </script>
14    </div>
15    <div class="content2">
16        <div id="ezoic-pub-ad-placeholder-102"></div>
17        <script>
18            ezstandalone.cmd.push(function() {
19                ezstandalone.showAds(102)
20            });
21        </script>
22    </div>
23    <div class="content3">
24        <div id="ezoic-pub-ad-placeholder-103"></div>
25        <script>
26            ezstandalone.cmd.push(function() {
27                ezstandalone.showAds(103)
28            });
29        </script>
30    </div>
31
32    ...
33
34    <!-- dynamic content + placeholders -->
35    <div class="dynamic content1">
36        <div id="ezoic-pub-ad-placeholder-104"></div>
37        <script>
38            ezstandalone.cmd.push(function() {
39                ezstandalone.showAds(104)
40            });
41        </script>
42    </div>
43    <div class="dynamic content2">
44        <div id="ezoic-pub-ad-placeholder-105"></div>
45        <script>
46            ezstandalone.cmd.push(function() {
47                ezstandalone.showAds(105)
48            });
49        </script>
50    </div>
51</body>

Advanced Usage

The advanced implementation provides additional functionality by accepting an array of objects. Each object can include the following attributes:

  • id (required): The unique identifier of the placeholder where the ad should be shown.
  • required (optional, boolean): A flag indicating whether the ad must be displayed. If set to `true`, the system will force an ad to be shown in the specified placeholder, even if it would not normally be displayed.
  • sizes (optional, string or array of strings): Specifies the allowed sizes for the ad in the format `'{width}x{height}'`. You can provide a single size as a string or multiple sizes as an array of strings. This allows you to control the dimensions of the ad that will be displayed.

Example Implementation

1<script>
2var placeholders = [
3    { id: 103, required: true, sizes: ['336x280', '126x126'] },
4    { id: 104, sizes: '1000x450' },  
5    { id: 105, required: true },
6];
7
8ezstandalone.showAds(placeholders);
9</script>

In this example:

  1. Placeholder 103:

    • An ad will always be displayed in placeholder `103`.
    • The allowed sizes for the ad are `336x280` and `126x126`.

  2. Placeholder 104:

    • An ad will be displayed in placeholder `104` if Ezoic decides this ad should be shown.
    • The allowed size for the ad is `1000x450`.

  3. Placeholder 105:

    • An ad will always be displayed in placeholder `105`.
    • No specific sizes are provided, so Ezoic will decide the best size for this placeholder.

Notes

  • Specificity of Ad Sizes: The ad sizes specified in the `sizes` attribute are treated as specific requests. Ezoic will attempt to find the best possible ad that fits the given size. If an exact match is not available, the system will choose the closest available size that can best fit within the specified dimensions.
  • If the `required` attribute is set to `true`, Ezoic will prioritize showing the ad in that placeholder, ensuring it is displayed even if other conditions might normally prevent it.
  • If `sizes` are specified, the ad will only be displayed if an ad of the specified sizes is available. If the `sizes` attribute is omitted or left empty, Ezoic will use its default behavior to determine the ad size.

Use Cases

  • Guaranteed Ad Placement: Use the `required` attribute to ensure that ads are shown in critical placeholders, regardless of other conditions.
  • Size-Specific Ads: Use the `sizes` attribute to control the dimensions of the ads being displayed. This is particularly useful for responsive designs or specific layout requirements where certain sizes are more effective.

This advanced method offers flexibility and control over ad placement, making it suitable for scenarios where more than just the placeholder ID is needed to dictate ad behavior.

RefreshAds

refreshAds is a new function in ezstandalone that allows for refreshing the ad for specific placeholders. This can be used if you would specifically like to refresh an ad for a viewer at a specific time. Below is an example of the function being used.

Current:

1<script>
2    ezstandalone.cmd.push(function() {
3        ezstandalone.refreshAds(101, 102)
4    });
5</script>