Features of ad tags

Tag reload

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

You can manage banner loading 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.

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

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

Ya.adfoxCode.reload(containerId)

<button onclick="Ya.adfoxCode.reload('adfox-id')">Reload</button>

Statistical samples for Yandex Advertising Network units

If you're using monetization, you can add the sample ID to the Adfox ad tag and collect separate statistics for each sample.

The sample ID is stored in a separate variable:

Specify the sample ID in the ad tag in the params block 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 placements. When embedding 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.

Ad experiments using Varioqub

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

Displaying fullscreen banners

Fullscreen units can display any banners, including third-party tags, Yandex Advertising Network banners, and banners from other demand platforms. There's no need for any extra wrappers. All required interstitial 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 these parameters to the Adfox ad tag on the required placement:

   • type: 'fullscreen';
   • platform: 'desktop' for the desktop version of the site;
   • platform: 'touch' for the mobile version of the site.
   Sample code for serving a banner in fullscreen mode

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

2. For placements with direct sales, add banners to your advertising campaign following the instructions and using relevant templates.

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

   1. Select the mobile site version.
   2. Set the ad unit type to Interstitial.
   3. Add advertising formats, such as display ads (banners), video ads, or standard design (text & image ads), and choose an impression strategy. Save the unit.

4. If you want to enable external monetization via Header Bidding, set it up following the instructions.

5. If you want to enable external monetization via Google, set it up following the instructions. We recommend using banner sizes 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 default display frequency is one ad impression per five minutes for each unique user, and it can't be changed.

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

   If the user closes the ad unit, a certain action can be performed in response, such as calling another ad unit. To do this, add the code with the action to onClose.

   Sample code for ad call with an 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
               }
         });
   });
   

Displaying fullscreen ad elements

• Banners added using the Fullscreen HTML5 templates are rendered in fullscreen mode, with interstitial ad elements defined by the banner parameters.
• Banners using other templates, including third-party tags, banners from the Yandex Advertising Network and external demand platforms, will also appear in fullscreen mode, with interstitial ad elements automatically added.
• The Adfox ad tag adds a substrate to fullscreen banners by default. If the Header Bidding demand platform wants to render the substrate manually, it can disable it in the Adfox code.

Displaying a Floor Ad

Adfox allows rendering banners in Floor Ad units across both the mobile and desktop site versions. In the unit, you can show ads from the Yandex Advertising Network and banners from external demand platforms, as well as direct sales or your own promo. This doesn't require any additional wrappers: all the necessary Floor Ad elements (the Close button, substrate) will be added automatically.

The Floor Ad unit appears two seconds after the page loads and remains anchored to the bottom of the screen, on top of the site's content. The user can close the ad at any time.

Unit size depends on the site version:

For more information about this unit, see the Yandex Advertising Network Help.

How to set up Floor Ad impressions

1. Add these parameters to the Adfox ad tag on the required placement:

   • type: 'floorAd'.
   • platform: 'desktop' — for the desktop site version.
   • platform: 'touch' — for the mobile site version.
   
   
   Sample code for rendering a Floor Ad unit on desktop

   <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 for desktop and mobile devices on the same page, add the unit code for each site version one after another.

   To check the site version and call the appropriate unit, you can 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') {
           // Calling FloorAd for the desktop version
           Ya.adfoxCode.create({
             ownerId: 264109,
             containerId: 'adfox_164750946031426465',
             type: 'floorAd',
             platform: 'desktop',
               params: {
                 p1: 'cdvyr',
                 p2: 'ghnb',
               }
           });
         } else {
           // Calling FloorAd 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. Choose the Floor Ad unit type, specify the name, and select the platform.
   2. Set up the unit and configure ad formats if needed.

   Find out how to configure this unit in the Yandex Advertising Network Help.

5. For placements with direct sales or custom promotional campaigns, add banners following these instructions and using the templates provided:

   • Banner HTML5.
   • Banner Image.
   • InPage video.
   • Code forwarding.
   • Banner Slider.
   • Banner Video.

6. If you enable external monetization via Header Bidding, set it up by following the instructions.

7. If you enable external monetization via Google, set it up by following these instructions.

   Warning

   When connecting external monetizers, direct sales, and promo campaigns, the maximum banner height can't exceed:

   • In the mobile version, 30% of the screen height. We recommend using banners of 320 × 100 or 320 × 50 pixels.
   • In the desktop version, 90 pixels.

Displaying a Top Ad

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

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

The unit's width is equal to the length of the short side of the screen. The unit height doesn't exceed 100 pixels. Ads with a larger height are fitted into the unit with size adjustment. For more information about this unit, see the Yandex Advertising Network Help.

How to set up Top Ad impressions

1. Add the type: 'topAd' parameter to the Adfox ad tag on the required placement.

   Sample code for rendering 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. Select the Top Ad unit type and specify its name.
   2. Set up the unit and configure ad formats if needed.

   Find out how to configure this unit in the Yandex Advertising Network Help.

4. For placements with direct sales or custom promotional campaigns, add banners following these instructions and using the templates provided:

   • Banner HTML5.
   • Banner Image.
   • Code forwarding.
   • Banner Slider.

5. If you enable external monetization via Header Bidding, set it up by following the instructions.

6. If you enable external monetization via Google, set it up by following these instructions.

   Warning

   When connecting external monetizers, direct sales, or promo campaigns, the maximum banner height can't exceed 100 pixels. We recommend using banners of 320 × 100 or 320 × 50 pixels.

Customize the look and feel of your native unit to match your site design

You can dynamically change the look and feel of your Yandex Advertising Network native unit for various site sections or design themes (for example, light or dark). To do this, add the darkTheme: true parameter to your ad tag. Sample code:

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

Customizing the widget's look and feel to match 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 from which the banner request was sent.

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 you enable the “Redefinition by referer” module in your account, the system will expect the site page address to be 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 dl. Add it to the request parameters if you want to redefine referer or dl.

Callback functions in the ad tag

You can use callback functions for non-dimensional banner types.

<script>
   window.yaContextCb.push(()=>{
        Ya.adfoxCode.create({
           ownerId: 208087,
           containerId: 'adfox',
           params: {
               pt: 'b',
               p1: 'bsoji'
           },
           onClose: () => { /* ad tag */ },
           onError: function(error) { /* ad tag */ },
           onLoad: function(data) { /* ad tag */ },
           onRender: function() { /* ad tag */ },
           onStub: function() { /* ad tag */ }
       })
   })
</script>

onClose

Called after the user has closed the ad. The function is available for fullscreen units and Floor Ad units.

onError

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

onError callback arguments:

Error type	Type	Description
type	String	`processBundleParams: The ad tag contains invalid parameters. The banner won't be served.
		adfoxBackend: The Adfox server has returned an error. The banner won't be served.
		userScriptError: The banner tag contains a syntax error. Whether or not the banner is served depends on the nature of the error.
message	String	Error description. Different browsers may return a different message for the same error, including a different amount of details.

onLoad

Сalled when a request receives a response that includes the window.loadAdfoxBundle object. Called before OnRender.

onLoad callback arguments:

Field	Type	Description
data.bundleName	String	Displays the name of a banner template (image, HTML-Creative, and other related names).
data.bundleParams	Object	Displays the template data used to render the banner.

onRender

Called when either the banner tag or the user-defined banner tag is placed inside a container.

onStub

Сalled when the server returns a placeholder (a system code), and the container is empty.

onVideoEnd

Сalled at the end of the video ad. The function is only available for InPage video format. When the player with an InPage video is minimized, the alternative code specified in the callback function runs.

Example of using an onVideoEnd callback function in the ad tag

<script>
    window.Ya.adfoxCode.create({
        ownerId: 123456,
        containerId: 'banner-inpage',
        params: {
            p1: 'clxao',
            p2: 'gwfm',
            insertAfter: 'undefined',
            insertPosition: '0',
            stick: true,
            stickTo: 'auto',
            stickyColorScheme: 'light'
        },
        // Callback function with the tag of the RTB unit rendered in the same container
        onVideoEnd: () => {
            Ya.Context.AdvManager.render({
                renderTo: "banner-inpage",
                blockId: "R-A-123456-1"
                }
            )
        }
    });
</script>

Skip token for the ad tag

When multiple Adfox ad tags on the page are linked to the same Yandex Advertising Network unit, it's highly likely that the same ad will be served from the Yandex Advertising Network.

To ensure protection against displaying identical ads, you can add the sequentialLoading: true option to the Adfox ad tag. In this case, Adfox units request ads sequentially, preventing ad duplication.

window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
        ownerId: 411614,
        sequentialLoading: true,
        containerId: 'containerId-1',
        params: {
            p1: 'cvtzm',
            p2: 'hvob',
        }
    })
})

Public API

All types of codes with the context.js library for creating an ad unit return an object. This object has five control 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 sent 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 where you need full control over the page status. The public API lets you prevent memory leaks and errors when destroying banners. When using 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.

Loading the context.js library synchronously

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 tag	Old asynchronous tag	Synchronous tag
   <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 ad tags

To add parameters to the ad tag:

• For asynchronous code, add them to the params object.
• For synchronous and XML code, add them to the Adfox server request string.

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

In the request parameters, you can pass the advertising IDs of user mobile devices. When passing multiple IDs in the request, only the one with the highest priority is used.

Available IDs in descending order of priority:

• google_aid: Android device ID (Google's identifier).
• huawei_oaid: Huawei device ID.
• idfa: iOS device ID.
• ifv: iOS device ID for apps from the same developer.
• ext_duid: External device ID.

Syntax for adding parameters to asynchronous 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 okay good 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

Send an email