ADFOX Sites Help

Header Bidding

О технологии

Header Bidding — это programmatic-технология, которая позволяет в момент загрузки страницы сайта пользователем, опросить напрямую несколько подключенных DSP платформ и выбрать среди них предложение с максимальной ставкой.

Издатель должен заключить с каждым покупателем отдельный договор для торгов с применением технологии Header Bidding, который не относится к Яндекс или ADFOX. При этом ответственность за некачественную рекламу, подобранную с использованием Header Bidding, несет сам покупатель.

Как работает Header Bidding: 1. В момент загрузки страницы сайта пользователем специальный код Header_bidding.js одновременно отправляет запросы всем подключенным покупателям и они конкурируют за показ на единых условиях, делая свои ставки. 2. Все ставки от покупателей приходят к серверу ADFOX вместе с рекламным запросом и сравниваются с CPM других кампаний вида "Динамическая монетизация" (если такие имеются в аккаунте издателя). Выбирается кампания с максимальной ставкой. 3. Кампания с максимальной ставкой перевзвешивается с Рекламной сетью Яндекса для выбора победителя: 3.1. Если РСЯ предлагает ставку больше, то РСЯ побеждает и получает право показать свою рекламу. 3.2. Если РСЯ не может предложить ставку больше или отказывается от участия в торгах, то побеждает рекламная кампания с максимальной ставкой и получает право показать свой баннер.

Преимущества использования Header Bidding для издателя:

  • удобный способ подключения внешних монетизаторов;
  • увеличение эффективности за счет учета ставок внешних монетизаторов в рамках ДМ;
  • снижение потерь трафика при схеме классических "водопадов";
  • сокращение времени для отрисовки рекламы за счет исключения "лишних" звеньев из водопада.

Список покупателей:

  • Criteo (в том числе с нативной рекламой)
  • Soloway
  • HPMD (Happy Monday)
  • Buzzoola
  • Mytarget
  • Videonow
  • Relap
  • IMHO (ADFOX)
  • Facebook
  • Between Digital
  • All in One Media
  • GetIntent
  • Tinkoff
  • RTB House
  • Pladform
  • ADFOX HB

Список будет пополняться


Настройка аккаунта ADFOX

Для запуска внешней монетизации выполните все этапы настройки. Важно, чтобы прослеживалась связь с монетизатором для ряда объектов: • в типе баннера шаблон для монетизатора N • рекламная кампания, в параметрах которой указан внешний монетизатор N • баннер в рекламной кампании, созданный с шаблоном монетизатора N • на сайте должен быть скрипт с настройками для запросов ставок от площадок к монетизатору N

1. Определите типы баннеров, на которых будет происходить размещение покупателей. При необходимости создайте новые типы баннеров.

1.1 К типам баннеров добавьте шаблоны для внешних монетизаторов header bidding. Перейдите в меню Настройки → Типы баннеров → Собственные → Безразмерные и кликните на значок Шаблоны . Нажмите "Использовать предзаданный" и добавьте в тип баннера шаблоны для покупателей. Шаблоны, подходящие для использования с header bidding технологией, именуются так:

Header Bidding {название покупателя} [loader]

2. Определите площадки для размещения покупателей и при необходимости создайте новые площадки.

3. Для каждого покупателя добавьте одну рекламную кампанию и в параметре Внешний монетизатор укажите покупателя в ADFOX.

Для всех монетизаторов, кроме IMHO (ADFOX) и ADFOX HB, значение CPM указывать не нужно, сервер получит его из ставки монетизатора и будет учитывать при выборе максимальной ставки среди всех кампаний уровня ДМ.

Для монетизатора <span class="tag_text">ADFOX HB</span> необходимо указывать <span class="tag_text">owner_id</span> — идентификатор аккаунта покупателя.

3.1 Создайте в кампаниях баннеры, используя шаблоны для монетизаторов. В диалоговых окнах добавления баннера будут доступны только типы баннеров, в которых есть шаблоны для покупателя, выбранного в параметрах кампании.

Например, если рекламная кампания создана для покупателя Criteo, а в тип баннера был добавлен шаблон "Header Bidding HPMD [loader]", то при добавлении баннера в такую кампанию, нельзя будет выбрать тип баннера, потому что в нем нет подходящего шаблона "Header Bidding Criteo [loader]".

4. Скопируйте идентификаторы (ID) созданных кампаний, они необходимы будут для дальнейших шагов по настройке конфигурационного скрипта на сайте. ID кампании можно получить на странице списка кампаний, как изображено на рисунке:

5. На сайте издателя все площадки, участвующие в Header Bidding, должны использовать коды вставки с библиотекой loader.js.

Монетизатор ADFOX HB

Монетизатор ADFOX HB — дает возможность издателю подключиться с помощью технологии Header Bidding к клиенту ADFOX (к селлинговым агентствам, использующим ADFOX) и отказаться от схемы с пробросами кодов между аккаунтами, установками заглушек и кодов возврата. Для подключения к монетизатору-клиенту ADFOX, издателю нужно: - заключить договор с монетизатором; - запросить код вставки ADFOX из аккаунта монетизатора.

Шаг 1. В аккаунте издателю необходимо произвести настройки под монетизатора, описанные в разделе Настройка аккаунта ADFOX, а именно: 1.1 Определить типы баннеров и площадки, на которых будет происходить размещение монетизаторов

1\.2 В типы баннеров, которые используются для площадок из п.1, добавить предзаданный шаблон для монетизатора ADFOX: **Header Bidding ADFOX [loader]**

1\.3 Добавить рекламную кампанию, выбрав монетизатора ADFOX HB и указать:

   • owner_id — идентификатор аккаунта монетизатора. Узнать его можно от монетизатора или из кода вставки монетизатора, например:          • CPM — CPM порог для монетизатора (для монетизатора ADFOX ставка указывается в параметрах кампании. Остальные Header Bidding монетизаторы делают свои ставки при получении запроса со страницы сайта).

1\.4 Добавить баннер в рекламную кампанию с монетизатором:

Шаг 2. С помощью [генератора](#HB-config) необходимо получить конфигурационный скрипт и [подключить скрипты](#3-2) для Header Bidding на сайт.

Пример конфигурационного скрипта с монетизатором ADFOX HB:

<script>
var adfoxBiddersMap = {
"adfox_example": "957356"
};
var adUnits = [
    {
        "code": "adfox_154875622348837699",
        "bids": [
            {
                "bidder": "adfox_example",
                "params": {
                "p1": "bxzlm",
                    "p2": "ekwz"
                }
            }
        ]
    }
];
var userTimeout = 500;
window.YaHeaderBiddingSettings = {
biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout
};
</script>

Что происходит в аккаунте монетизатора ADFOX

Монетизатор ADFOX в своем аккаунте может работать в обычном режиме.

В ходе запроса рекламы от площадки издателя, в аккаунте монетизатора выбор будет проходить по кампаниям: - с видом "Гарантия"; - прямых продаж с видом "Динамическая монетизация"; - с видом "Промо".

Исключаются из выбора кампании: - Сделки; - с видом "Динамическая монетизация":    - Монетизация РСЯ;    - Кампании внешних монетизаторов.

Статистика по загрузкам будет засчитываться только если РК монетизатора выиграла в торгах и произошел показ баннера монетизатора ADFOX на площадке издателя.


Настройка скриптов на сайте

Конфигурационный скрипт для запросов ставок

Создайте скрипт одним из способов:

  1. С помощью генератора конфигурационного скрипта (рекомендуем).

Объект с настройками добавьте в неймспейс window.YaHeaderBiddingSettings

window.YaHeaderBiddingSettings = { biddersMap: BiddersMap; adUnits: AdUnit; timeout: Timeout; }

biddersMap — объект с парами 'ключ': 'значение', где:

ключ — название покупателя в одинарных кавычках (см. в Таблице покупателей);

значение — идентификатор рекламной кампании, созданной на 11 уровне Динамической монетизации, для данного покупателя, в одинарных кавычках.

'betweenDigital': '787336'

adUnits — массив объектов с информацией о том, среди каких покупателей разыгрывать объявления.

AdUnit [
      {
          code: string;
          sizes: Sizes;
          bids: [
              {
                  bidder: string; // ключ покупателя
                  params: any; // настройки для конкретного покупателя
              }
          ];
      }
  ]

code — идентификатор контейнера для баннера на сайте издателя (равен containerId в коде вставки ADFOX); sizes — размеры баннера, обязательный параметр для: Soloway, Between Digital, Facebook. Массив массивов, в котором 1-ое значение ширина, а 2-ое - высота.

sizes: [[ 728, 90 ]];

bids — данные о покупателях, подключенных к торгам для этой площадки, представляет собой массив объектов:

bidder — название покупателя см. столбец ключ в Таблице покупателей; params — объект с парами 'параметр площадки': 'значение', где:

параметр площадки — настройка для конкретного покупателя (см. столбец "Параметр площадки в params" в Таблице покупателей); значение — идентификатор площадки покупателя, необходимо его получить от покупателя.

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

Для монетизаторов IMHO (ADFOX) и ADFOX HB объект params заполняется парами 'параметр': 'значение' из объекта params кода вставки монетизатора ADFOX:

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

timeout — время ожидания ответа от сервера покупателя, рекомендуемое время 500мс (максимально возможное 3000мс, но в таком случае скорость загрузки основного контента сайта будет производиться с задержкой).

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

ПокупательКлюч покупателяНеобходимость передачи sizes в adUnitsID среза в Партнёрском ИнтерфейсеПараметр площадки в params
Criteocriteoнет222placementId
Solowayadriverда333
HPMDhpmdнет666
Buzzoolabuzzoolaнет777
MytargetmyTargetнет444
Facebookfacebookда888
Between DigitalbetweenDigitalда1110
All in One Mediaaioнет1554
GetIntentgetintentнет1665
Tinkofftinkoffнет1776
Videonowvideonowнет2109
RTB Housertbhouseнет2220
Relaprelapнет
Pladformpladformда
IMHO (ADFOX)adfox_imho-bannersнетпеременные из объекта params кода вставки монетизатора
ADFOX HBadfox_{owner_name}, где {owner_name} — название аккаунта-монетизаторанетпеременные из объекта params кода вставки монетизатора

Подключение скриптов

• в любом месте страницы асинхронно добавьте скрипт header-bidding.js;

<script async src="https://yastatic.net/pcode/adfox/header-bidding.js"></script>

• в head страницы разместите конфигурационный скрипт для запроса ставок, полученный в генераторе или созданный вручную.

• в head страницы один раз добавьте [библиотеку loader.js](/page/45/#2).

<script src="https://yastatic.net/pcode/adfox/loader.js" crossorigin="anonymous"></script>

    <div class="row_line"><div class="alert_box question_box"><p markdown="1">

Если для контейнера используется функция перезагрузки кода (метод reload), то при перезагрузке контейнера осуществляется повторный запрос ко всем покупателям, заданным для этого контейнера в объекте adUnits.
Если сайт с бесконечной подгрузкой контента, в том числе с рекламными местами, и требуется осуществить новые запросы к покупателям, используйте инструкцию.

<head>
<script async src="https://yastatic.net/pcode/adfox/header-bidding.js"></script>
<script>
var adfoxBiddersMap = {
'criteo': '710398',
    'adriver': '737037',
    'hpmd': '737040',
    'adfox_example': '168627'
};
var 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'
                }
            }
        ]
    }
];
var userTimeout = 500;
window.YaHeaderBiddingSettings = {
biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout
};


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

В методе **YaHeaderBiddingSettings** доступен callback **onBidsRecieved**, который вызывается в момент окончания опроса всех покупателей и получения от них ставок.
В качестве аргумента передаются ставки, полученные с последнего запроса к покупателям в следующем формате: [массив с объектом Bid](#5-1).

Новый запрос к покупателям <span data-placement="top" data-toggle="tooltip" class="tooltip_element symbol_question" data-original-title="Новые запросы к покупателям будут отправлены при перезагрузке рекламного места или вызове метода pushAdUnits."></span> и его завершение вызовет этот callback повторно.

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

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

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

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

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

var adfoxBiddersMap = { 'criteo': '781965' };

var adUnits = [{ code: 'adfox_151663576557768486', bids: [{ bidder: 'criteo', params: { placementId: 1168582, nativeCallback: function(json) { renderCriteo(json); console.log('Hello world'); } } } ]

}]; var userTimeout = 500;

window.YaHeaderBiddingSettings = { biddersMap: adfoxBiddersMap, adUnits: adUnits, timeout: userTimeout };

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

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

Для новых рекламных мест, добавленных по мере загрузки нового контента, можно описать новый набор покупателей с помощью вызова метода:

window.Ya.headerBidding.pushAdUnits(AdUnit[])

где вместо AdUnit[] — укажите массив объектов с информацией о том, к каким покупателям делать запрос ставок для новых добавленных рекламных мест.

    Метод **pushAdUnits** необходимо вызывать до **adfoxCode.create** для нового баннерного места.

В описании объектов containerId элементов должен отличаться от ранее сохраненных в конфигурационном скрипте, при этом сам конфигурационный скрипт в head страницы изменять не нужно.

Пример вызова метода для нового рекламного места:

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

Инструмент для проверки ставок покупателей

В результате загрузки одной страницы сайта, запросы ставок к покупателям могут быть отправлены неоднократно, а именно в случаях:

1. Запросы ко всем покупателям, указанным в конфигурационном скрипте, при загрузке страницы; 2. При перезагрузке рекламного места с помощью reload() происходит повторный опрос покупателей, относящимся только к перезагружаемому объявлению; 3. При вызове метода pushAdUnits() происходит опрос только по указанным в нем покупателям.

Метод **getLastBidsReceived** позволяет получить ставки с последнего опроса покупателей.

В ответе получаем массив, заполненный объектами Bid для каждой пары рекламное место + покупатель.
Объект может содержать только одно из полей:

• banner — в случае ответа покупателя обычным баннером; • error — в случае ошибки; • native — в случае ответа от покупателя нативным баннером.

Вызовите метод:

window.Ya.headerBidding.getLastBidsReceived();

Пример вызова метода в консоли браузера:

interface Bid {
adapterName: string; // имя покупателя
containerId: string; // идентификатор контейнера
campaignId: number; // идентификатор рекламной кампании в ADFOX
requestDuration: number; // длительность запроса
cost?: {
currency: string; // валюта "RUB"/"USD"
cpm: number; // ставка, которая пришла с сервера за 1000 показов
},
    banner?: {
    src: string; // содержимое баннера
},
    size?: {
    width: number; // ширина в px
    height: number; // высота в px
},
    error?: {
    code: number; // код ошибки
    message: string; // имя ошибки
},
    native?: {
    nativePayload: any; // объект с содержимым для нативного показа
}
};

Расшифровка кодов ошибок: 0 — неизвестная ошибка; 1 — отсутствие ставки/ответа; 2 — некорректный ответ; 3 — таймаут; 4 — ошибка HTTP протокола; 5 — некорректные пользовательские данные в конфигурационном скрипте; 6 — некорректные настройки биддера (только для Facebook); 7 — биддер прислал Id контейнера, отличный от Id в запросе; 8 — биддер прислал корректный ответ без статуса.


Отчеты по Header Bidding

В аккаунте, в котором подключены монетизаторы, на уровне сайта и общих отчетов доступны [отчеты по Header Bidding](/page/196).