Ad tag features

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:

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.

Experiments on ads with Varioqub

You can conduct experiments on ads placed on your site using Varioqub. This tool lets you create an experiment with multiple options and both change the elements and layout of the site and compare different ad units and their settings. As a result of your experiment, you get statistics for indicators that help determine which option is most effective in terms of monetization and user metrics. For more information, see Varioqub experiments in Help.

Displaying fullscreen banners in the site mobile version

Fullscreen units in the site mobile version can serve any banners, including third-party tags and banners from the Yandex Advertising Network or other monetizers. 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.

Example of a fullscreen banner displaying

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.

Displaying Floor Ad units

With Adfox, you can serve banners in Floor Ad units in both the mobile and desktop versions of your site. In the unit, you can serve ads from the Yandex Advertising Network and external monetizers, as well as direct sales or custom promo materials. You don't need any additional wrappers for this: all the necessary Floor Ad elements (the Close button and a background) are added automatically.

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

The unit size depends on the site version:

Learn more about the unit in Help for Yandex Advertising Network.

Example of a Floor Ad unit in the mobile version

Unit position in vertical and horizontal orientation:

Example of a Floor Ad unit in the desktop version

How to set up Floor Ad placements

1. Add the following parameters to the Adfox tag for the placement:

   • type: 'floorAd'.
   • platform: 'desktop' for the desktop version.
   • platform: 'touch' for the mobile version.

   Sample ad tag for serving a Floor Ad unit in the desktop version

   <div id="adfox_164750946031426465"></div>
   <script>
     window.yaContextCb.push(()=>{
       Ya.adfoxCode.create({
         ownerId: 264109,
         containerId: 'adfox_164750946031426465',
         type: 'floorAd',
         platform: 'desktop',
         params: {
           p1: 'cdvyr',
           p2: 'ghnb',
         }
       })
     })
   </script>  

2. Place the received tag on the site page between the <body> and </body> tags.

3. To display a Floor Ad unit on the same page on both desktop and mobile devices, add the unit tag for each site version one after another.

   To check the site version and call the corresponding unit, add the Ya.adfoxCode.getPlatform() method to the ad tag.

   Example of calling a Floor Ad unit for desktop and mobile devices

   <script>
     window.yaContextCb.push(() => {
         if (Ya.adfoxCode.getPlatform() === 'desktop') {
           // сalling a Floor Ad unit for the desktop version
           Ya.adfoxCode.create({
             ownerId: 264109,
             containerId: 'adfox_164750946031426465',
             type: 'floorAd',
             platform: 'desktop',
               params: {
                 p1: 'cdvyr',
                 p2: 'ghnb',
               }
           });
         } else {
           // сalling a Floor Ad unit for the mobile version
           Ya.adfoxCode.create({
             ownerId: 264109,
             containerId: 'adfox_164750946031426466',
             type: 'floorAd',
             platform: 'touch',
               params: {
                 p1: 'cdvyr',
                 p2: 'ghnb',
               }
           });
         }
     });    
   </script>

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

   1. Set the unit type to Floor Ad, name the unit, and select a placement.
   2. Configure settings for the unit and, if necessary, set the advertising formats.

   Learn more about the unit settings in Help for Yandex Advertising Network.

5. If the site features direct sales or custom promo campaigns, follow the instructions and use the templates to add banners:

   • Banner HTML5.
   • Banner Image.
   • InPage video.
   • Code forwarding.
   • Banner Slider.
   • Banner Video.
6. If you enable external monetization via Header Bidding, set it up using the instructions.
7. If you enable external monetization via Google, set it up using the instructions.

   Important. If you enable external monetizers, direct sales, and promo campaigns, your banner height can't be more than:

   • Mobile version — 30% of the screen height. Recommended banner sizes: 320 × 100 or 320 × 50 pixels.
   • Desktop version — 90 pixels.

Displaying Top Ad units

You can add a Floor Ad unit in the mobile version of your site. In the unit, you can serve ads from the Yandex Advertising Network and external monetizers, as well as direct sales or custom promo materials. You don't need any additional wrappers for this: all the necessary Top Ad elements (the Close button and a background) are added automatically.

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

The unit width matches the length of the shorter side of the screen. The unit height can't exceed 100 pixels. If an ad's height exceeds this limit, it'll be resized to fit the unit. Learn more about the unit in Help for Yandex Advertising Network.

Example of a Top Ad unit

Unit position in vertical and horizontal orientation:

How to set up Top Ad placements

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

   Sample ad tag for serving a Top Ad unit

   <div id="adfox_164750946031426465"></div>
   <script>
     window.yaContextCb.push(()=>{
       Ya.adfoxCode.create({
         ownerId: 264109,
         containerId: 'adfox_164750946031426465',
         type: 'topAd',
         params: {
           p1: 'cdvyr',
           p2: 'ghnb',
         }
       })
     })
   </script>  

2. Place the received tag on the site page between the <body> and </body> tags.

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

   1. Set the unit type to Top Ad and name the unit.
   2. Configure settings for the unit and, if necessary, set the advertising formats.

   Learn more about the unit settings in Help for Yandex Advertising Network.

4. If the site features direct sales or custom promo campaigns, follow the instructions and use the templates to add banners:

   • Banner HTML5.
   • Banner Image.
   • Code forwarding.
   • Banner Slider.
5. If you enable external monetization via Header Bidding, set it up using the instructions.
6. If you enable external monetization via Google, set it up using the instructions.

   Important. If you enable external monetizers, direct sales, and promo campaigns, your banner height can't be more than 100 pixels. Recommended banner sizes: 320 × 100 or 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.

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 backup ad (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>
   window.yaContextCb.push(()=>{
        Ya.adfoxCode.create({
           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.

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,