Ручная настройка конфигурационного скрипта

Создание конфигурационного скрипта

Совет. Вы можете сгенерировать скрипт в интерфейсе Adfox с помощью HB конфигуратора.
Конфигурационный скрипт для установки на ваш ресурс можно создать вручную. Для этого объект с настройками добавьте в неймспейс window.YaHeaderBiddingSettings.
window.YaHeaderBiddingSettings = {
    biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout,
    trustedOwners: [123456,111111]
}
Укажите нужные параметры:
  • biddersMap — объект с парами 'ключ': 'значение', где:
    • ключ — название покупателя в одинарных кавычках (см. в Таблице покупателей);
    • значение — идентификатор рекламной кампании, созданной на 11 уровне Динамической монетизации, для данного покупателя, в одинарных кавычках.
    'betweenDigital': '787336'
  • adUnits — массив объектов с информацией о том, среди каких покупателей разыгрывать объявления.
       AdUnit [
          {
              code: string; 
              sizes: Sizes; 
              bids: [
                  {
                      bidder: string; // ключ покупателя
                      params: any; // настройки для конкретного покупателя
                  }
              ];
          }
      ]                                      
    • code — идентификатор контейнера для баннера (равен containerId в коде вставки Adfox);
    • codeType — тип рекламного запроса, который вы хотите получать в этом рекламном месте. Принимает значения:
      • combo — для получения и InPage, и баннерной рекламы;
      • inpage — для получения только InPage рекламы;
      • instream — для получения только InStream рекламы.

      Если в ответе приходит json/html или параметр codeType не задан, будет показана медийная реклама.

    • sizes — размеры баннера, обязательный параметр для некоторых покупателей (см. столбец «Необходимость передачи sizes в adUnits» в Таблице покупателей). Массив массивов, в котором 1-е значение ширина, а 2-е — высота.
      sizes: [[ 728, 90 ]];
    • bids — данные о покупателях, подключенных к торгам для этой площадки, представляет собой массив объектов:
      • bidder — название покупателя см. столбец «Ключ покупателя» в Таблице покупателей;
      • params — объект с парами 'параметр площадки': 'значение', где:
        • параметр площадки — настройка для конкретного покупателя (см. столбец «Параметр площадки в params» в Таблице покупателей);
        • значение — идентификатор площадки покупателя, необходимо его получить от покупателя.

      Пример содержания массива bids:

      {
       bidder: 'betweenDigital',
       params: {
         placementId: 8
       },
      }

      Объект params может содержать необязательные элементы:

      • параметр sendTargetRef: true — передает referer, содержащий URL страницы, на которой пользователь кликнул по баннеру;
      • объект additional — содержит дополнительные параметры в запросе к биддеру для принятия решения о выкупе показа.

      Пример с необязательными элементами объекта params:

      {
       bidder: 'betweenDigital',
       params: {
         placementId: "8",
         sendTargetRef: true, // referer
         additional: { // дополнительные параметры запроса
           pos: 123,
           ref: 'my-site/page'
         },
       },
      }
      Массив adUnit с необязательными элементами params
         AdUnit [
            {
                code: string; 
                sizes: Sizes; 
                bids: [
                {
                  bidder: 'mytarget',
                  params: {
                    placementId: "320552",
                    sendTargetRef: true, // referer
                    additional: { // дополнительные параметры запроса
                      pos: 123,
                      ref: 'my-site/page'
                    },
                  },
                }
                ];
            }
        ]                                      
      Для монетизаторов, работающих через Adfox HB, объект params заполняется парами 'параметр': 'значение' из объекта params кода вставки монетизатора:
      {bidder: 'adfox_example', params: {'p1': 'bxzlm', 'p2': 'ekwz'}
  • timeout — время ожидания ответа от сервера покупателя, рекомендуемое время 500 мс (максимально возможное 3000 мс, но в таком случае скорость загрузки основного контента сайта будет производиться с задержкой).
  • trustedOwners (необязательный параметр) — если вы планируете передавать ставки в запросы других аккаунтов Adfox через шаблон Проброс кода Adfox [context], укажите идентификаторы аккаунтов, коды из которых будут пробрасываться.

Таблица с данными покупателей

Покупатель Ключ покупателя Необходимость передачи sizes в adUnits Поддержка In-Stream video Поддержка combo*

(подробнее см. ниже)

Параметр площадки в params
Criteo criteo нет нет да placementId
Soloway adriver да да да
HPMD (Happy Monday) hpmd нет да нет
Buzzoola buzzoola да нет да
Mytarget myTarget нет нет да
Between Digital betweenDigital да да да
All in One Media aio нет нет нет
GetIntent getintent нет нет нет
Tinkoff tinkoff нет нет нет
Videonow videonow нет нет да
Relap relap нет нет нет
Pladform pladform да нет нет
Alfasense alfasense да нет нет
Fotostrana fotostrana нет нет нет
Hybrid hybrid да нет да
Mgid mgid да нет нет
DGT SSP dgt_ssp нет нет нет
ADSPEND adspend да нет нет
MediaToday mediatoday нет нет нет
Redllama redllama нет нет нет
Qvant DSP qvant_dsp да нет нет
Adtelligent adtelligent нет нет нет
OTM otm нет да нет
Segmento segmento да да нет
Bidvol bidvol да нет нет
Sape sape нет да да
Astralab astralab нет нет да
AdMixer AdMixer нет нет да
Gnezdo Gnezdo нет нет нет
MTS mts нет да да
Media Instinct Group mit нет нет да
Kadam kadam нет нет нет
MediaSniper mediasniper да нет да
IMHO (через Adfox HB) adfox_imho-banners нет да да переменные из объекта params кода вставки монетизатора
Другие монетизаторы, работающие через Adfox HB adfox_{owner_name}, где {owner_name} — название аккаунта-монетизатора нет нет да переменные из объекта params кода вставки монетизатора
Внимание. Combo-аукцион поддерживают только те монетизаторы, которые указаны в таблице выше в столбце «Поддержка combo». На одном рекламном месте нельзя сочетать монетизаторов, которые поддерживают combo, c монетизаторами, которые не поддерживают combo. Если на вашем рекламном месте предполагается смешанный combo-аукцион, подключайте к нему только монетизаторов с поддержкой combo. Ставки от монетизаторов, не поддерживающих combo, будут игнорироваться.

Для покупателей Criteo и Soloway ранее использовались параметры площадки zoneid и siteid. С ними сохранена обратная совместимость, но рекомендуем перейти на использование placementId.

Callback о выполнении запроса к покупателям

В методе YaHeaderBiddingSettings доступен callback onBidsReceived, который вызывается в момент окончания опроса всех покупателей и получения от них ставок.

В качестве аргумента передаются ставки, полученные с последнего запроса к покупателям в следующем формате: массив с объектом Bid.

Новый запрос к покупателям и его завершение вызовет этот callback повторно.

Пример добавления callback onBidsReceived:

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

Решение для сайтов с «бесконечной» прокруткой

Сайт с «бесконечной» прокруткой — это сайт, на страницах которого новые части контента и новые рекламные места подгружаются без перезагрузки страницы. Если на страницах такого сайта используется header bidding, для новых рекламных мест аукцион разыгрываться не будет, так как ставки были сделаны при первой загрузке и уже использованы в подборе рекламы.

Вы можете описать новый набор покупателей для новых рекламных мест, добавленных по мере загрузки контента. Для этого используйте метод window.Ya.headerBidding.pushAdUnits(AdUnit[]), где вместо AdUnit[] — нужно указать массив объектов с информацией, к каким покупателям делать запрос ставок для новых добавленных рекламных мест.

  1. Перед вызовом метода для нового рекламного места добавьте инициализацию новых очередей. Для этого в элементе head замените код загрузчика context.js:

    Старый код Новый код
    <script>window.yaContextCb = window.yaContextCb || []</script>
    <script src="https://yandex.ru/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.ru/ads/system/context.js" async></script>
  2. Добавьте метод pushAdUnits в код блока. Обратите внимание, что:
    • для нового баннерного места метод pushAdUnits необходимо вызывать до adfoxCode.create;
    • в описании объектов containerId элементов должен отличаться от ранее сохраненных в конфигурационном скрипте, при этом сам конфигурационный скрипт в head страницы изменять не нужно.

    Пример итогового кода для рекламного места будет выглядеть так:
    <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>

Подключение нативной рекламы Criteo

В массиве adUnits найдите значение code, для которого нужно добавить нативную рекламу.

В объект bids добавьте параметр nativeCallback, содержащий в себе функцию function(json), где json — объект, полученный в ответе от Criteo.

Далее напишите функцию, распоряжающуюся этим содержимым, вставляющую его в верстку, и т. д.

Если в function(json), как и в нашем примере, используется вызов функции, она должна быть объявлена в глобальной области видимости.

Пример конфигурационного скрипта с нативной рекламой
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
};

Подключение дополнительных таргетингов через Adfox HB

Если в аккаунте монетизатора, работающего через Adfox HB, настроены Дополнительные таргетинги, в код вставки необходимо добавить параметры puidN, где N — номер характеристики от 1 до 63, вместе со значениями таргетирования. Параметры puid добавляются в объект params в формате name: value, где name — это название параметра (puidN), а value — его значение.

Пример конфигурационного скрипта с монетизатором, работающим через Adfox HB, и добавленными параметрами puid
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
};

Вызов cookie-sync пикселей при запросе к биддеру

Со страницы, на которой вы разместили код, можно вызывать cookie-sync пиксели параллельно с запросом. Ссылку на пиксель предоставляет монетизатор.

Чтобы вызвать cookie-sync пиксель, пропишите его в конфигурационном скрипте в массиве window.YaHeaderBiddingSettings.syncPixels.

Пример конфигурационного скрипта с cookie-sync пикселем для монетизатора Sape
window.YaHeaderBiddingSettings = {
    biddersMap: { 'sape': '1648783' },
    adUnits = [{
        code: 'adfox - container - id',
        bids: [{
            bidder: 'sape',
            params: { placementId: '634996' }
        }]
    }],
    syncPixels = [{
        bidder: 'sape',
        pixels: ['https://ssp-rtb.sape.ru/rmatch/.....']
    }]
    timeout = 1000
};