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: 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:

Set 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 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 these parameters to the Adfox ad tag on the required placement:

   • type: 'fullscreen';
   • platform: 'desktop' for the desktop site version.
   • platform: 'touch' for the mobile site version.
   Sample code for displaying 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. If a placement has direct sales, add banners to an advertising 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 mobile site version.
   2. Set the ad unit type to Fullscreen.
   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 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 at least 160 pixels wide and no more than 600 pixels 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, enter the code with the action in onClose.

   Example tag for calling an ad 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 interstitial ad elements

• Banners added using the Fullscreen HTML5 templates will be rendered fullscreen with the fullscreen ad elements defined in the banner parameters.
• Banners based on other templates, including third-party tags, Yandex Advertising Network and external monetizer banners, will also be rendered fullscreen and interstitial ad elements will be added automatically.
• 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.

Impression 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 2 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:

To learn more about the unit, see 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.

   To learn more about unit setup, see the Yandex Advertising Network Help section.

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 demand platforms, 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.

Impression 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. To learn more about the unit, see 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.

   To learn more about unit setup, see the Yandex Advertising Network Help section.

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 demand platforms, 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>

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 embed code and list a class array inside it, such as:

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

Personal data usage

If you need to manage user consent for serving personalized ads, you can configure data collection using these parameters:

• gdpr-consent-flag: For users in Europe.
• cookie-consent-flag: For users from other countries.

Depending on the user's choice, these parameters accept a value of 0 or 1. If a site user denies permission to collect and process their personal data, a value of 0 is passed to the parameter in the ad tag. As a result, when the ad is served:

• The site doesn't store advertising cookies.
• The site user's personal data isn't used for targeting.

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

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 when the user closed the ad. The function is available for fullscreen units and Floor Ad units.

onError

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

Callback onError arguments:

Type of error	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 tag 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 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.

onRender

Called when the banner tag or the tag 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.

onVideoEnd

Called at the end of the ad video. 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>

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

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 tag	Old asynchronous tag	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 embed codes

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: Google Android device ID.
• 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 for 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