Creating and placing a script on the site

Creating a configuration script

  1. Prepare an ad tag for a placement:

    • If you haven't added an ad tag to the site yet, get one by following the instructions.
    • If the tag is already embedded in the site, take it from the layout.

    In the ad tag, find the containerId parameter and copy its value. You'll need the ID when creating a script.

  2. Create a script using the HB configurator:

    1. Go to Monetization → HB configurator.

      Note

      The configurator is only available if you have campaigns with an external monetizer.

    2. Click Add container. Specify the Container ID: insert the containerId parameter value you copied earlier from the ad tag.

    3. Select the type of ad request that you want to receive in this placement: Banner, Combo, InPage, or InStream. For more information about connecting the InStream ad request type, see Enabling InStream video ads.

      Warning

      From monetizers integrated with the Prebid library, only banner ads are available.

    4. Click Add monetizer.

    5. Specify the banner width and height in pixels: for example, [300, 300]. This parameter is mandatory for Prebid monetizers and some Yandex Header Bidding monetizers.

    6. Select monetizers and specify their parameters:

      • For Yandex Header Bidding monetizers, specify the Monetizer's placement ID (Placement ID). You can find the Placement ID in the monetizer interface.

        Table with Yandex Header Bidding monetizer data
        Monetizer Monetizer key The requirement to pass the sizes parameter InStream video Combo* support (to learn more, see below) The placement parameter in params
        AdMixer AdMixer no no yes placementId
        ADSPEND adspend yes no no placementId
        Adtelligent adtelligent no no no placementId
        Adwile adwile no no no placementId
        Alfasense alfasense yes no no placementId
        All in One Media aio no no no placementId
        Astralab astralab no no yes placementId
        A-traffic atraffic yes no no placementId
        Between Digital betweenDigital yes yes yes placementId
        Bidvol bidvol yes yes yes placementId
        Buzzoola buzzoola yes no yes placementId
        Criteo criteo no no yes placementId
        DGT SSP dgt_ssp no no no placementId
        Fotostrana fotostrana no no no placementId
        GetIntent getintent no no no placementId
        Gnezdo Gnezdo no yes no placementId
        Hybrid hybrid yes no yes placementId
        Kadam Kadam no no no placementId
        Media Instinct Group mit no no yes placementId
        MediaSniper mediasniper yes yes yes placementId
        Mediatoday mediatoday no no no placementId
        MTS mts no yes yes placementId
        MyTarget myTarget no no yes placementId
        Native Rent nativerent no no no placementId
        Otclick HB otclick yes yes yes placementId
        OTM otm no yes no placementId
        Qvant DSP qvant_dsp yes no no placementId
        Redllama redllama no no no placementId
        Relap relap no no no placementId
        Roxot roxot yes yes yes placementId
        Sape sape no yes yes placementId
        Segmento segmento yes yes yes placementId
        SMI2 smi2 no yes yes placementId
        Soloway adriver yes yes yes placementId
        Solta solta yes yes yes placementId
        Tinkoff tinkoff no no no placementId
        UMG umg yes yes yes placementId
        Videonow videonow no no yes placementId
      • The mandatory and optional parameters for monetizers integrated with the Prebid.js library are different. The table below shows which parameters are mandatory depending on the monetizer.

        Table with Prebid monetizer data
        Monetizer Monetizer key Mandatory parameters Optional parameters
        AdKernel pb_adkernel host (string)

        zoneId (integer)
        adkernel_prebid.org
        AdRiver pb_adriver siteid(integer)

        placementId (string)
        adriver_prebid.org
        AppNexus pb_appnexus placementId (integer) appnexus_prebid.org
        Between Digital pb_between s (string) between_prebid.org
        CPMStar pb_cpmstar placementId (integer) cpmstar_prebid.org
        Getintent pb_getintent pid (integer) getintent_prebid.org
        Hybrid pb_hybrid placeId (string)

        placement (string)
        hybrid_prebid.org
        Index Exchange pb_ix siteId (string) ix_prebid.org
        myTarget pb_mytarget placementId (string) mytarget_prebid.org
        OpenX pb_openx delDomain (string)

        unit (string)
        openx_prebid.org
        Programmatica pb_programmatica siteId(string)

        placementId (string)
        programmatica_prebid.org
        PubMatic pb_pubmatic publisherId (string) pubmatic_prebid.org
        Rich Audience pb_richaudience pid (string)

        supplyType (string)
        richaudience_prebid.org
        Rubicon Project pb_rubicon accountId (integer)

        siteId (integer)

        zoneId (integer)
        rubicon_prebid.org
        Sape pb_sape placeId (integer) rtbsape_prebid.org
        Silverpush pb_silverpush publisherId (string) silverpush_prebid.org
        VOX pb_vox placementId (string)

        placement (string)
        vox_prebid.org

        You can get all the parameters in the monetizer interface.

      • For monetizers working via Adfox HB, specify params from the ad tag. These parameters must be requested from the connected monetizer.

        Table with Adfox HB monetizer data
        Monetizer Monetizer key The need to pass sizes to adUnits InStream video support Combo* support (to learn more, see below) The placement parameter in params
        Digital Alliance adfox_imho-banners no yes yes variables from the params object of the monetizer ad tag
        Other monetizers that use Adfox HB adfox_{owner_name}, where {owner_name} is the monetizer account name no no yes variables from the params object of the monetizer ad tag

      Alert

      You can't combine monetizers that support combo with ones that don't in a single placement. If you plan a mixed combo auction for your placement, only include monetizers that support combo. Bids from monetizers that don't support combo are ignored.

    7. If there are multiple placements on the page, click Add container, specify the containerId of another placement, and add monetizers the same way.

    8. In the User Timeout field, enter the waiting time for a response from the monetizer's server in milliseconds.

    9. The Trusted Owners field is optional. If you plan to send bids to other Adfox account requests via the Adfox code forwarding [loader] template, specify the IDs of the accounts where the codes are forwarded from, separating them by commas.

    10. Click Generate. After the script appears in the field on the right, click Copy.

  3. If there are Prebid monetizers in the script, don't forget to install the Prebid.js library and add a script with a library call.

  4. Place the resulting script on the site.

    Warning

    The ad loader code shouldn't be repeated on the page and should be below the script with the Header Bidding settings. That way, the loader can determine that the page contains Header Bidding and identify which ads should wait for bids. If the loader code was already installed, delete the superfluous one.

  5. Embed an ad unit's ad tag where you want to serve ads. If you already added an ad tag to the site, don't change it.

Example of a single script for Yandex Header Bidding and Prebid.js

Note

For a detailed description of the script parameters, see the example below.

<!-- Example of calling Prebid.js -->
<script src="https://example.ru/libraries/prebid.js"></script>
<!-- Calling header-bidding.js -->
<script async src="https://yandex.ru/ads/system/header-bidding.js"></script>
        
<script>

  // Prebid.js library API
  var pbjs = pbjs || {};
  pbjs.que = pbjs.que || [];
        
  // Object with params 'buyer key': 'campaign ID'
  var adfoxBiddersMap = {
    'criteo': '2637485',
    'pb_pubmatic': '2647539', 
    'adfox_imho-banners': '2567834'
  };

  // Object with 'monetizer key': bid multiplier pairs
  var biddersCpmAdjustmentMap = {
      'pb_pubmatic': 3,
      'adfox_imho-banners': 3.5
  };
  
  // Array of objects with buyer data
  var adUnits = [
    {
      code: 'adfox_hb', // containerId from Adfox ad tag
      sizes: [[300, 250]], // Banner sizes
      bids: [ // Buyer data
        {
          bidder: 'criteo', // Buyer key for Yandex Header Bidding monetizer
          params: { placementId: '917087' } // placementID from monetizer account
        }
        {  
          bidder: 'pb_pubmatic', // Buyer key for monetizer integrated with Prebid.js
          params: { publisherId: '32572' } // publisherId parameter from PubMatic account
        }
        {
          bidder: 'adfox_imho-banners', // Buyer key for Adfox HB monetizer
          params: { p1: 'bxzlm', p2: 'ekwz' } // Parameters from Adfox HB monetizer ad tag
        }        
      ]
    },
  ];
        
  var userTimeout = 2000; // Timeout from buyer’s service
  
  // Namespace with settings
  window.YaHeaderBiddingSettings = {
    pbjs: pbjs, // Required parameter if Prebid monetizers are connected
    biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout,
    biddersCpmAdjustmentMap: biddersCpmAdjustmentMap
  };
</script>

<!-- Ad loader -->
<script> window.yaContextCb = window.yaContextCb || []</script> 
<script src="https://yandex.ru/ads/system/context.js" async></script>
Script parameter descriptions

Parameter

Description

pbjs

Prebid.js library API. A mandatory element if you connect monetizers integrated with Prebid.js. The parameter must be set to pbjs.

For example:
 var pbjs = pbjs || {};
 pbjs.que = pbjs.que || []; 

biddersMap

The object with 'key': 'value' pairs, where:

  • key: The monetizer key in single quotes. Monetizer keys can be found in the monetizer data tables (see step 2.6 in the instructions above).
  • value: The ID of the campaign created at the 11th Dynamic monetization level for the selected monetizer in single quotes.
For example:
'betweenDigital': '787336' 

biddersCpmAdjustmentMap

Optional parameter. The object with 'key': 'value' pairs, where:

  • key: The monetizer key in single quotes. Monetizer keys can be found in the tables with monetizer data (see step 2.6 in the instructions above).

  • value: Multiplier applied to the monetizer's bids. With the multiplier, you can prioritize monetizers (for example, if one sends gross CPM and another sends net CPM).

    The value format is an integer or decimal number from 0 to 5 inclusive (up to three decimal places are supported).

adUnits

An array of objects with information about which monetizers to auction ads off to. It contains:

  • code: The banner container ID (same as containerId in the Adfox ad tag).

  • codeType: The type of ad request that you want to receive in this placement. Takes the following values:

    • combo: For receiving both InPage and banner ads.
    • inpage: For receiving only InPage ads.
    • instream: For receiving only InStream ads.

    If the response contains json/html or the codeType parameter isn't set, a banner ad is served.

  • sizes: The banner dimensions. A mandatory parameter for monetizers integrated with Prebid.js and some other monetizers (see the monetizer data table in step 2.6 above).

    An array of arrays in which the first value is a width and the second value is a height.

    For example:
    sizes: [[ 728, 90 ]]; 
    
  • bids: Data on monetizers connected to the auction for this placement. It is an array of objects:

    • bidder: Monetizer key.

    • params: The object with 'placement parameter': 'value' pairs, where:

      • placement parameter: Setting for a specific monetizer.
      • meaning: The set of parameters to get from the monetizer.

      The contents of the params object depend on the monetizer:

      • For Yandex Header Bidding monetizers: Placement ID :value.

        Example of bids for the Between Digital monetizer
        {
          bidder: 'betweenDigital',
          params: {
            placementId: 8
          },
        }
        
      • For monetizers integrated with Prebid.js, see the list of parameters in step 2.6 of the instructions above.

        Example of bids for the AdRiver monetizer (Prebid)
        {
          bidder: 'pb_adriver',
          params: {
            'siteid': 216200
            'placementId': '55:test_placement'
          },
        }
        
      • For monetizers working via Adfox HB, fill in the 'parameter': 'value' pairs from the params object in the monetizer ad tag.

        For example:
        {
          bidder: 'adfox_example',
          params: {
            'p1': 'bxzlm',
            'p2': 'ekwz'
          },
        }
        

      The params can include an optional element, namely the additional object with additional request parameters determined by agreement with the monetizer.

      Example with optional parameters of the params object
      {
        bidder: 'betweenDigital',
        params: {
          placementId: '8',
          additional: { // Additional request parameters       pos: 123,
            ref: 'my-site/page'
          },
        },
      }
      
      The adUnit array with optional params elements
      AdUnit 
      [
        {
          code: string; 
          sizes: Sizes; 
          bids: [
            {
              bidder: 'mytarget',
              params: {
                placementId: '320552',
                additional: { // Additional request parameters             pos: 123,
                  ref: 'my-site/page'
                },
              },
            }
          ];
        }
      ]                                    
      

timeout

The timeout for a response from the monetizer's server. The recommended timeout is 500 ms. The maximum possible value is 3000 ms, but the main content of the site will load with a delay if this value is specified.

trustedOwners

Optional parameter. If you plan to send bids to other Adfox account requests via the Adfox code forwarding [context] template, specify the IDs of the accounts where the codes are forwarded from.

Other examples of scripts with header-bidding.js

Example of embedding scripts and placing placements
<head>       
  <script src="https://yandex.ru/ads/system/header-bidding.js" async></script>
  <script>
    window.YaHeaderBiddingSettings = {
      biddersMap: {
        criteo: '710398',
        adriver: '737037',
        hpmd: '737040',
        adfox_example: '168627'
      },
      adUnits: [
        {
          code: 'adfox_1',
          bids: [
            {
              bidder: 'criteo',
              params: { placementId: '917087' }
            }
          ]
        },
        {
          code: 'adfox_2',
          sizes: [[ 728, 90 ]],
          bids: [
            {
              bidder: 'criteo',
              params: { placementId: '917087' }
            },
            {
              bidder: 'adriver',
              params: { placementId: '762890' }
            },
            {
              bidder: 'adfox_example',
              params: { p1: 'bxzlm', p2: 'ekwz' }
            }
          ]
        },
        {
          code: 'adfox_3',
          bids: [
            {
              bidder: 'hpmd',
              params: { placementId: '2360' }
            }
          ]
        }
      ],
      timeout: 500
    };
  </script>
  <script>window.yaContextCb = window.yaContextCb || []</script>
  <script src="https://yandex.ru/ads/system/context.js" async></script>
</head>
<body>
  <div id="adfox_1"></div>
  <script>
    window.yaContextCb.push(()=>{
      Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_1',
        params: { pp: 'g', ps: 'cnsf', p2: 'frnp' }
      })
    })
  </script>
  <div id="adfox_2"></div>
  <script>
    window.yaContextCb.push(()=>{
      Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_2',
        params: { pp: 'g', ps: 'cnsh', p2: 'frnq' }
      })
    })
  </script>
  <div id="adfox_3"></div>
  <script>
    window.yaContextCb.push(()=>{
      Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_3',
        params: { pp: 'g', ps: 'cnsh', p2: 'frny' }
      })
    })
  </script>
</body>
Example of connecting InPage ads
<script async src="https://yandex.ru/ads/system/header-bidding.js"></script>
        <script>
            var adfoxBiddersMap = {
              "smi2": "2714950",
              "adfox_example_sdk": "2502029"
            };

            var adUnits = [
              {
                "code": "slot",
                "codeType": "inpage",
                "bids": [
                  {
                    "bidder": "smi2",
                    "params": {
                      "placementId": "101131"
                    }
                  },
                  {
                    "bidder": "adfox_example_sdk",
                    "params": {
                      "p1": "cwdyt",
                      "p2": "hiuy"
                    }
                  }
                ]
              }
            ];

            var userTimeout = 1500;

            window.YaHeaderBiddingSettings = {
               biddersMap: adfoxBiddersMap,
               adUnits: adUnits,
               timeout: userTimeout,
            };
        </script>
        <script>
            window.yaContextCb = window.yaContextCb || []
        </script>
        <script src="https://yandex.ru/ads/system/context.js" async></script>
<div id="slot" style="width: 640px; margin: 0 auto;"></div>
Example of connecting Combo ads
<script src="https://yandex.ru/ads/system/header-bidding.js" async></script>
<script>
  window.YaHeaderBiddingSettings = {
    biddersMap: { buzzoola: '776727', betweenDigital: '1114942' },
    adUnits: [
      {
        code: 'adfox_156536764866112926',
        codeType: 'combo',
        bids: [
          { bidder: 'buzzoola', params: { placementId: '296669' } },
          { bidder: 'betweenDigital', params: { placementId: '3263439' } }
        ]
      }
    ],
    timeout: 1000
  }; 
</script>
<script>window.yaContextCb = window.yaContextCb || []</script>
<script src="https://yandex.ru/ads/system/context.js" async></script>
Example of connecting InStream ads
<script src="https://yandex.ru/ads/system/header-bidding.js" async></script>
<script>
           var adfoxBiddersMap = {
              "smi2": "2714950",
              "adfox_example_sdk": "2502029"
            };

            var adUnits = [
              {
                "code": "adfox-container-id",
                "codeType": "instream",
                "bids": [
                  {
                    "bidder": "smi2",
                    "params": {
                      "placementId": "101131"
                    },
                    "adBreakTypes": [
                      "preroll",
                      "postroll"
                    ]
                  },
                  {
                    "bidder": "adfox_example_sdk",
                    "params": {
                      "p1": "cwdyt",
                      "p2": "hiuy"
                    },
                    "adBreakTypes": [
                      "preroll",
                      "postroll"
                    ]
                  }
                ]
              }
            ];

            var userTimeout = 1500;

            window.YaHeaderBiddingSettings = {
               biddersMap: adfoxBiddersMap,
               adUnits: adUnits,
               timeout: userTimeout,
            };
 </script>
 <script src="https://yandex.ru/ads/system/context.js" async></script>
<script type="text/javascript" charset="utf-8" src="https://yandex.ru/ads/system/adsdk.js"></script>

Demo pages

Use the links below to view examples of banners where Header Bidding is used.

InPage video

In-Stream video

Contact support

Send an email