Set up the configuration script manually

Creating a configuration script

You can generate a script to be installed on your resource in the Adfox interface using the HB configurator or you can create one manually.

To create a script manually, add an object to the window.YaHeaderBiddingSettings namespace with the following settings:
window.YaHeaderBiddingSettings = {
  biddersMap: adfoxBiddersMap,
  adUnits: adUnits,
  timeout: userTimeout,
  trustedOwners: [123456,111111]
}

Specify the parameters:

Parameter Description
biddersMap The object with 'key': 'value' pairs, where:
  • key: The bidder key in single quotes.
  • value: The ID of the campaign created at the 11th Dynamic monetization level for the selected bidder in single quotes.
For example:
'betweenDigital': '787336'
adUnits

An array of objects with information about which bidders to auction off ads 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 display ad is served.

  • sizes: A banner size. This parameter is required for some bidders. An array of arrays where the first value is the width and the second value is the height.
    For example:
    sizes: [[ 728, 90 ]];
  • bids: Data on bidders that are connected to the auction for this placement. An array of objects:
    • bidder: A bidder key.
    • params: The object with 'placement parameter': 'value' pairs, where:
      • placement parameter: The setting for a specific bidder.
      • value: The bidder's placement ID that you need to get from the bidder.
    Example of the bids array content
    {
     bidder: 'betweenDigital',
     params: {
       placementId: 8
     },
    }

    The params object may contain optional elements:

    • The sendTargetRef: true parameter passes a referer containing the page URL where the user clicked the banner.
    • The additional object contains additional parameters in the request to the bidder for making a decision about buying the impression.
    Example with optional parameters of the params object
    {
     bidder: 'betweenDigital',
     params: {
       placementId: "8",
       sendTargetRef: true, // referer
       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",
            sendTargetRef: true, // referer
            additional: { // additional request parameters           pos: 123,
              ref: 'my-site/page'
            },
          },
        }
        ];
      }
    ]                                   
    For monetizers working through Adfox HB, fill in the params object with 'parameter': 'value' pairs from the params object in the monetizer ad tag:
    {bidder: 'adfox_example', params: {'p1': 'bxzlm', 'p2': 'ekwz'}
timeout The timeout for a response from the bidder's server. The recommended timeout is 500 ms. The maximum possible value is 3000 ms, but the main content of the website 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.

Bidder data table

Buyer Bidder key The need to pass sizes to adUnits In-Stream video support Combo* support

(to learn more, see below)

The placement parameter in params
Criteo criteo no no yes placementId
Soloway adriver yes yes yes
HPMD (Happy Monday) hpmd no yes no
Buzzoola buzzoola yes no yes
MyTarget myTarget no no yes
Between Digital betweenDigital yes yes yes
All in One Media aio no no no
GetIntent getintent no no no
Tinkoff tinkoff no no no
Videonow videonow no no yes
Relap relap no no no
Pladform pladform yes no no
Alfasense alfasense yes no no
Fotostrana fotostrana no no no
Hybrid hybrid yes no yes
Mgid mgid yes no no
DGT SSP dgt_ssp no no no
ADSPEND adspend yes no no
MediaToday mediatoday no no no
Redllama redllama no no no
Qvant DSP qvant_dsp yes no no
Adtelligent adtelligent no no no
OTM otm no yes no
Segmento segmento yes yes yes
Bidvol bidvol yes yes yes
Sape sape no yes yes
Astralab astralab no no yes
AdMixer AdMixer no no yes
Gnezdo Gnezdo no no no
MTS mts no yes yes
Media Instinct Group mit no no yes
Kadam Kadam no no no
MediaSniper mediasniper yes no yes
Adwile adwile no no no
Solta solta yes yes yes
СlicksСloud clickscloud no no no
NetBanners netbanners yes no no
Digital Alliance (via Adfox HB) 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
Attention. You can't combine monetizers that support combo with monetizers that don't in one 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.

Previously, the zoneid and siteid placement parameters were used for Criteo and Soloway bidders. They're still backward compatible, but we recommend switching to placementId.

The onBidsReceived callback function

In the YaHeaderBiddingSettings method, the onBidsReceived callback function is available. It's called when the bidder survey ends and bids are received.

As an argument, the bids received after the last bidder request are passed in the following format: an array with the Bid object.

A new request to the bidders and its completion triggers this callback function again.

Example of adding the onBidsReceived function
window.YaHeaderBiddingSettings = {
  biddersMap: adfoxBiddersMap,
  adUnits: adUnits,
  timeout: userTimeout,
  callbacks: {
    onBidsReceived: (bids) => {
      console.log('---> PUBLIC CALLBACK onBidsReceived: ', bids);
    }
  }
};

A solution for websites with “infinite” scroll

On websites with infinite scroll, new content and new placements load without reloading the page. If you use Header Bidding on pages of this kind of a website, there's no auction for new placements. This is because the bids were made at the initial page response and were already used for ad selection.

To describe a new set of bidders for new placements that are added as new responses, use the window.Ya.headerBidding.pushAdUnits(AdUnit[]) method. Instead of AdUnit[], you need to specify an array of objects with information about which bidders can be asked to bid for newly added placements.

  1. Before calling the method for a new placement, add initialization of new queues. To do this, replace the context.js loader code in the head element:

    Old code New code
    <script>
    window.yaContextCb = window.yaContextCb || []
    </script>
    <script src="https://yandex.com/ads/system/context.js" async>
    </script>
    <script>
    window.Ya || (window.Ya = {});
    window.yaContextCb = window.yaContextCb || [];
    window.Ya.adfoxCode || (window.Ya.adfoxCode = {});
    window.Ya.adfoxCode.hbCallbacks || (window.Ya.adfoxCode.hbCallbacks = []);
    </script>
    <script src="https://yandex.com/ads/system/context.js" async>
    </script>
    Copied to clipboard
  2. Add the pushAdUnits method to the unit code. Please note the following:
    • For a new banner placement, the pushAdUnits method must be called before adfoxCode.create.
    • In the object description, the elements' containerId must differ from those previously saved in the configuration script, but you don't need to change the configuration script itself in the page head.

Example of final code for the placement
<div id="adfox_15218"></div>
<script>window.Ya.adfoxCode.hbCallbacks.push(function() {
    window.Ya.headerBidding.pushAdUnits([
        {
          code: 'adfox_15218',
          sizes: [[728, 90]],
          bids: [
            { bidder: 'adriver', params: { placementId: 'adfox_test' } }
          ]
        }
    ]);
    window.yaContextCb.push(function() {
        window.Ya.adfoxCode.create(
            {
               ownerId: 168627,
               containerId: 'adfox_15218',
               params: { p1: 'bzzvh', p2: 'fvxb' }
          }
        );
    });
});
</script>

Enable native Criteo ads

To add native Criteo ads:

  1. In the adUnits array, find the code value.
  2. Add a nativeCallback parameter containing the function(json) function to the bids object, where json is the object received in the Criteo response.

If the function call is used in function(json), it must be declared in the global viewable area.

Example of a configuration script with native ads
window.YaHeaderBiddingSettings = {
  biddersMap: { 'criteo': '781965' },
  adUnits: [{
    code: 'adfox_151663576557768486',
    bids: [{
      bidder: 'criteo',
      params: {
        placementId: 1168582,
        nativeCallback: function(json) {
          renderCriteo(json);
          console.log('Hello world');
        }
      }
    }]                
  }],
  timeout: 500
};

Enable custom targeting via Adfox HB

If a monetizer account that uses Adfox HB has custom targeting set up, you need to add the puidN parameters and targeting values to the ad tag, where N is the characteristic number from 1 to 63. The puid parameters are added to the params object in name: value format, where:

  • name is the parameter name (puidN).
  • value is the parameter value.
Example of a configuration script with a monetizer that uses Adfox HB and the added puid parameters
window.YaHeaderBiddingSettings = {
  biddersMap: { 'adfox_example': '957356' },
  adUnits: [{
    code: 'adfox_154875622348837699',
    bids: [{
      bidder: 'adfox_example',
      params: {
        pp: 'g',
        ps: 'cqmv',
        p2: 'fqnq',
        puid1: 'woman',
        puid2: '16:17:18:19',
        puid3: 'green'
      }
    }]
  }],
  timeout: 500
};

Call the cookie-sync pixels when a request is sent to the bidder

From the page where you placed the ad tag, you can call cookie-sync pixels at the time of the request. The pixel link is provided by the monetizer.

To call a cookie-sync pixel:

  1. Declare a variable and add the pixel link to it. If you have multiple links, add them to the pixels array as a comma-separated string.

    var syncPixels = [{
        bidder: 'sape',
        pixels: ['https://ssp-rtb.sape.ru/rmatch/.....']
      }]
  2. Add a call for the pixels to the YaHeaderBiddingSettings section:

    syncPixels: syncPixels
Example of a configuration script with a cookie-sync pixel for the Sape monetizer
<script>
  var adfoxBiddersMap = {
    'sape': '1648783'
  };

  var adUnits = [
    {
      code: 'adfox_container_id',
      bids: [
        {
          bidder: 'sape',
          params: {
            placementId: '634996'
          }
        }
      ]
    }
  ];

  var userTimeout = 500;

  var syncPixels = [
    {
      bidder: 'sape',
      pixels: [
        'https://ssp-rtb.sape.ru/rmatch/1',
        'https://ssp-rtb.sape.ru/rmatch/2'
      ]
    }
  ];

  window.YaHeaderBiddingSettings = {
    biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout,
    syncPixels: syncPixels
  };
</script>

Contact support