Ad tag features

  1. Ad tag reload
  2. Statistics samples for ad units
  3. Displaying fullscreen banners in the site mobile version
  4. Floor Ad or Top Ad displaying in the site mobile version
  5. Adapting the widget appearance to the site design
  6. Redefinition by referer
  7. Callback functions in the ad tag
  8. Skip token for the ad tag
  9. Public API
  10. Synchronous loads of the context.js library
  11. Passing additional parameters to the ad tags
  12. Syntax for adding parameters for asynchronous ad tags

Ad tag reload

Reloading the ad tag lets you make repeated requests to the Adfox system without reloading the entire page (for example, on the site pages where the user spends a lot of time when viewing a photo gallery or taking tests).

You can manage ad responses using the containerId and onlyIfWasVisible parameters:

Ya.adfoxCode.reload(containerId, {onlyIfWasVisible: true});

Parameter values:

  • containerId is the ID of the element that contains the banner. If you need to reload all the placements, specify null instead of containerId.
  • onlyIfWasVisible indicates whether to check if the container is in the viewable area of the screen in order to reload:
    • true: Placements in the viewable area of the user's screen are reloaded.
    • false or missing parameter: Reloading is performed for the specified containers regardless of whether they are in the viewable area of the screen.
Reloading all containers in the viewable area
Ya.adfoxCode.reload(null, {onlyIfWasVisible: true});
Reloading one specific container (regardless of whether it's in the viewable area)
Ya.adfoxCode.reload(containerId, {onlyIfWasVisible: false});

or

Ya.adfoxCode.reload(containerId)
Example of calling a placement reload with the adfox-id container ID
<button onclick="Ya.adfoxCode.reload('adfox-id')">Reload</button>

Statistics samples for ad units

If you use monetization, you can additionally set the sample ID in the Adfox ad tag and collect separate statistics for samples.

The sample ID is set in a separate variable:

Variable name Description Data type
partner-stat-id Sample ID A number from 1 to 1000000000
Variable name Description Data type
partner-stat-id Sample ID A number from 1 to 1000000000

Set the sample ID in the ad tag in the params unit when placing ads on the site. For example:

<div id="adfox_1485963383642980"></div>
<script>
  window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
      ownerId: 232598,
      containerId: 'adfox_1485963383642980',
      params: {
        p1: 'bufhf',
        p2: 'fbao',
        'partner-stat-id': '34567'
      }
    })
  })
</script>

The sample ID in the example is 34567.

You can also specify it in the ad tags of other ad placements to view aggregate statistics for these ad placements. When placing the ad tag from a placement on other pages, you can specify a different sample ID to view statistics separately for each placement. You can generate a statistical report with grouping by sample in the Yandex Advertising Network interface under Statistics.

Displaying fullscreen banners in the site mobile version

Previously, in Adfox, a fullscreen banner could only be displayed in the mobile version of the site in the following cases:

  • In direct sales using the Fullscreen HTML5 template.
  • In campaigns with the Yandex Advertising Network or other monetizers, using their own wrappers to display third-party banners in fullscreen mode.

Now we have improved the feature to display a fullscreen banner in the mobile version of the site: any banners, including third-party codes, banners from the Yandex Advertising Network or other monetizers, can be shown in fullscreen mode. This doesn't require any additional wrappers: all the necessary fullscreen ad elements (the Close button, a countdown timer to close a banner, and a substrate) will be added automatically.


How to set up the display of fullscreen banners
  1. Add the type: 'fullscreen' parameter to the Adfox ad tag for the desired placement.
    Example of the ad tag for displaying a banner in fullscreen mode
    window.yaContextCb.push(()=>{
  Ya.adfoxCode.create({
    ownerId: 264109,
    containerId: 'adfox_164750946031426465',
    type: 'fullscreen',
    params: {
      p1: 'cdvyr',
      p2: 'ghnb',
    }
  })
})
  2. If a placement has direct sales, add banners to a campaign according to the instructions, using the necessary templates.
  3. If you enable monetization with the Yandex Advertising Network, configure the ad unit parameters as follows:
    1. Select the site mobile version.
    2. Set the unit type to Fullscreen.
    3. Add advertising formats, such as media ads (banners), video ads, or standard design (text & image ads), and choose a display strategy. Save the unit.
  4. If you enable external monetization via Header Bidding, set it up by following the instructions.
  5. If you enable external monetization via Google, set it up by following the instructions. We recommend using banner sizes that are at least 160 px wide and no more than 600 px high.

  6. If necessary, set an impression limit at the placement level. The impression frequency you define will apply to all campaigns on the chosen placement in Adfox: direct sale campaigns, Yandex Advertising Network campaigns, and campaigns where Header Bidding is used.

    For Yandex Advertising Network units created in Adfox, the impression frequency is set by default and doesn't change: it's 1 impression in 5 minutes for a unique user.

  7. To find out when the ad was closed, add the onClose callback function.

    In response to the user closing an ad unit, you can perform an action, for example, call another ad unit. To do this, enter the tag with the action in onClose.

    Example of an ad code with the onClose function:
    window.yaContextCb.push(function () {
      Ya.adfoxCode.create({
            containerId: 'adfox_112233445566',
            ownerId: 11223344,
            params: {
                  dl: 'https://my-cool-site.ru/',
                  p2: 'fkds',
                  pp: 'h',
                  ps: 'cmky'
            },
            type: 'fullscreen',
            onClose: () => {
                  // action performed by the placement after the banner is closed
            }
      });
});
Specifics of displaying elements of fullscreen ads
  • Banners added using the Fullscreen HTML5 templates will be rendered fullscreen with the fullscreen ad elements that are set in the banner parameters.
  • Banners based on other templates, including third-party codes, Yandex Advertising Network and external monetizer banners, will also be rendered fullscreen and any elements of fullscreen ads will be added automatically.

Floor Ad or Top Ad displaying in the site mobile version

You can add a Floor Ad or Top Ad unit in the mobile site version. In the unit, you can display ads from the Yandex Advertising Network and external monetizer banners, as well as direct sales and promo campaigns. This doesn't require any additional wrappers: all the necessary Floor Ad or Top Ad elements (the Close button, a substrate) will be added automatically.

Note. You cannot place both Top Ad and Floor Ad on the same page.
Floor Ad

The Floor Ad unit appears two seconds after the page is opened and is fixed at the bottom of the screen on top of site content. The user can close the ad at any time.

The unit width is equal to the length of the short side of the screen. The maximum height of the ad in the Floor Ad unit can't be more than 30% of the long side of the screen. Ads with a greater height will fit into the unit with resizing. To learn more about the unit, see the Yandex Advertising Network Help.

Example of a Floor Ad unit
Top Ad

The Top Ad unit appears two seconds after the page is opened and is fixed at the top of the screen on top of site content. The user can close the ad at any time.

The unit width is equal to the length of the short side of the screen. The unit height can't be more than 100 pixels. Ads with a greater height will fit into the unit with resizing. To learn more about the unit, see the Yandex Advertising Network Help.

Example of a Top Ad unit
How to set up the display of Floor Ad or Top Ad

  1. Add the type: 'floorAd' or type: 'topAd' parameter to the Adfox ad tag for the placement.

    Example of the tag for displaying a Floor Ad unit
    <div id="adfox_164750946031426465"></div>
<script>
  window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
      ownerId: 264109,
      containerId: 'adfox_164750946031426465',
      type: 'floorAd',
      params: {
        p1: 'cdvyr',
        p2: 'ghnb',
      }
    })
  })
</script>

  2. Paste the ad tag into the HTML code of your website between the <body> and </body> tags.

  3. If you enable monetization with the Yandex Advertising Network, configure the RTB unit parameters as follows:

    1. Select the mobile version of the site.
    2. Set the unit type to Floor Ad or Top Ad.
    3. You can skip the format selection window: the set of formats in the Floor Ad and Top Ad units is preset and can't be changed.
    4. Select an impression strategy and save the unit.

  4. If a placement has direct sales or promo campaigns, add banners by following the instructions and using templates:

  5. If you enable external monetization via Header Bidding, set it up by following the instructions.
  6. If you enable an external Google monetizer, set it up by following the instructions.
    Important. When connecting external monetizers, direct sales, and ad campaigns, the banner height can't be more than:
    • For Floor Ads: 30% of the screen height.
    • For Top Ads: 100 pixels.
    We recommend using banners that are 320 × 100 and 320 × 50 pixels.

Adapting the widget appearance to the site design

You can dynamically change the appearance of the recommendation widget created in Adfox for different site sections or design themes (for example, light or dark). To do this, add the additionalClasses parameter to the ad tag and list an array of classes in it. For example:

<script>
  Ya.adfoxCode.create({
    ownerId: 208087,
    containerId: 'adfox',
    params: {
      p1: 'cmrtz',
      p2: 'gqqu',
      puid1: '',
      puid2: ''
    },
    insertionCodeParams: {
      additionalClasses: ['dark', 'light'],
    }
  });
</script>

Redefinition by referer

Referer is the address of the site page that the banner request was sent from.

By default, the site page URL is passed in the HTTP request headers and is used to identify the site sections and check URL-based targeting.

If the “Redefinition by referer” module is enabled in the account, this means that the address of the site page is expected in the dl or ld request parameter.

  • dl (document.location): Passed by default in ad tags with the context.js library. If no address is passed in the dl parameter, the value from the HTTP request header is used.
  • ld (document.location.href): This parameter takes priority over the dl. Add it to the request parameters if redefinition of the referer or dl values is required.

Callback functions in the ad tag

Ad tags for nondimensional banner types let you use callback functions:

onClose

Called when the user closed the ad. The function is available for the fullscreen unit and the Floor Ad unit.

onError

Called if the request returns a network error (for example, 404) or the banner code contains a syntax error.

Callback onError arguments:

Error type Type Description
type String processBundleParams: Incorrect parameters are specified in the ad tag, the banner won't be served.
adfoxBackend: The Adfox server returns an error, the banner won't be served.
userScriptError: The banner code contains a syntax error, the banner will or won't be served depending on the error.
message String An error description. Different browsers may return a different message for the same error, including a different amount of details.
Error type Type Description
type String processBundleParams: Incorrect parameters are specified in the ad tag, the banner won't be served.
adfoxBackend: The Adfox server returns an error, the banner won't be served.
userScriptError: The banner code contains a syntax error, the banner will or won't be served depending on the error.
message String An error description. Different browsers may return a different message for the same error, including a different amount of details.
onLoad

Called when a response to the request is received and it contains the window.loadAdFoxBundle object. Called before OnRender.

Callback onLoad arguments:

Field Type Description
data.bundleName String Displays the name of a banner template (image, HTML-Creative, and so on).
data.bundleParams Object Displays the template data based on which the banner will be rendered.
Field Type Description
data.bundleName String Displays the name of a banner template (image, HTML-Creative, and so on).
data.bundleParams Object Displays the template data based on which the banner will be rendered.
onRender

Called when the banner code or the code of the default banner (user-defined) is embedded in the container.

onStub

Called when the server returns a placeholder (system code), the container remains empty.

Example of using callback functions in the ad tag
<script>
     Ya.adfoxCode.createScroll({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
            pt: 'b',
            p1: 'bsoji'
        },
        onClose: () => { /* some code */ },
        onError: function(error) { /* some code */ },
        onLoad: function(data) { /* some code */ },
        onRender: function() { /* some code */ },
        onStub: function() { /* some code */ }
    });
</script>

Skip token for the ad tag

If several Adfox ad tags on a page are associated with one Yandex Advertising Network unit, it is highly likely that the same ad will come from the Yandex Advertising Network.

To enable protection against the display of identical ads, we recommend adding the sequentialLoading: true option to the Adfox ad tag. It includes the sequential loading of ads by Adfox units, which prevents duplicates from being displayed.

Note. This option only works with ads in the Yandex Advertising Network and doesn't affect direct sales.
Example of using a skip token
window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
        ownerId: 411614,
        sequentialLoading: true,
        containerId: 'containerId-1',
        params: {
            p1: 'cvtzm',
            p2: 'hvob',        
        }
    })
})

Public API

All types of ad tags with the context.js library for creating an ad unit return an object. This object has five management methods:

  1. destroy: Destroys the banner and clears the container where the ad is inserted.
  2. initialize: Recreates the banner that was destroyed by the destroy method. When calling this method, an ad request is made to the server. If the banner was not destroyed by the destroy method, nothing happens.
  3. reload: Reloads the banner. In this case, the session ID (pr) remains unchanged. In fact, this is a combined call of the destroy and initialize methods. Hidden banners are not reloaded, since browsers sometimes render banners incorrectly in hidden units. When calling the method for a hidden or uninitialized banner, no reload occurs.
  4. hide: Hides the banner without destroying it. The banner container becomes hidden using the display: none style.
  5. show: Shows the hidden banner by removing the display: none style for the container. No request is sent to the server in this case.

The Public API is great for single-page apps for which full control over the page status is critical. The Public API lets you prevent memory leaks and errors when destroying banners. Under reinitialization, all the callback functions that were passed to the banner parameters are executed again.

Ya.adfoxCode.clearSession(); method: Use it to change the session ID (pr) on the page for all subsequent requests.

Synchronous loads of the context.js library

Ad tags and the context.js library are loaded asynchronously.

If necessary, you can implement synchronous loads of the context.js library, but this may slow down the site.

To convert the code:

  1. In the library connection line, remove the async attribute.
    <script src="https://yandex.ru/ads/system/context.js"></script>
  2. Edit all the ad tags that have already been inserted into the site. You'll also need to change any new ad tags.

    Synchronous ad tags don't use the yaContextCb, adfoxAsyncParams, adfoxAsyncParamsScroll, or adfoxAsyncParamsAdaptive call queues.

    New asynchronous code Old asynchronous code Synchronous code 
    <script>
  window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
      ownerId: 208087,
      containerId: 'adfox',
      params: {
        pt: 'b',
        p1: 'bsoji'
      }
    })
  })
</script>
    		 
    <script>
(function(w, n) {
    w[n] = w[n] || [];
    w[n].push({
        ownerId: 208087,
        containerId: 'adfox-id',
        params: {
            pt: 'b',
            p1: 'bsoji'
        }
    });
})(window, 'adfoxAsyncParams');
</script>
    		 
    <script>
  Ya.adfoxCode.create({
    ownerId: 208087,
    containerId: 'adfox',
    params: {
      pt: 'b',
      p1: 'bsoji'
    }
  })
</script>
    New asynchronous code Old asynchronous code Synchronous code 
    <script>
  window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
      ownerId: 208087,
      containerId: 'adfox',
      params: {
        pt: 'b',
        p1: 'bsoji'
      }
    })
  })
</script>
    		 
    <script>
(function(w, n) {
    w[n] = w[n] || [];
    w[n].push({
        ownerId: 208087,
        containerId: 'adfox-id',
        params: {
            pt: 'b',
            p1: 'bsoji'
        }
    });
})(window, 'adfoxAsyncParams');
</script>
    		 
    <script>
  Ya.adfoxCode.create({
    ownerId: 208087,
    containerId: 'adfox',
    params: {
      pt: 'b',
      p1: 'bsoji'
    }
  })
</script>

Passing additional parameters to the ad tags

You can add parameters to the ad tags either in the params object (for asynchronous ad tags) or in the Adfox server request string (for synchronous and XML codes).

When substituting the pk parameter values, no value encoding is required.

Syntax for adding parameters for asynchronous ad tags

name: value,
  • If the value is text, enclose it in single quotes.

  • If the value is a variable name, leave it without quotes.

  • If a new parameter is added last, no comma is required at the end.

Example 1. Adding puid1 with a single value and puid2 with multiple colon-separated values

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                puid1: 'value1',
                puid2: 'value1:value2:value3:value4'
                }

Example 2: Adding eid1 with the firstEid value

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                eid1: 'firstEid'
                }

Example 3. Adding the pk parameter with a single keyword

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'great',
                pke: '1'
                }

Example 4. Adding the pk parameter with multiple space-separated keywords

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'great quite all right excellent',
                pke: '1'
                }
Example 5. Adding the pk parameter with a keyword. Only one keyword can be passed.
params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'great excellent',
                pke: '1'
                }

Contact support