ADFOX Sites Help

Header Bidding

Статья была обновлена

10.10.2019

Генератор скрипта Header Bidding

О технологии

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

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

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

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

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

Демо-cтраницы:
Десктопная версия сайта
Мобильная версия сайта
InPage video

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

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

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

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

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

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

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

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

Для монетизатора ADFOX HB необходимо указывать owner_id — идентификатор аккаунта покупателя.

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. С помощью генератора необходимо получить конфигурационный скрипт и подключить скрипты для Header Bidding на сайт.

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

Пример конфигурационного скрипта с монетизатором ADFOX HB и добавленными параметрами puid:

<script async src="https://yastatic.net/pcode/adfox/header-bidding.js"></script>
<script>
var adfoxBiddersMap = {
"adfox_example": "957356"
};
var adUnits = [
    {
        "code": "adfox_154875622348837699",
        "bids": [
             {
                "bidder": "adfox_example",
                "params": {
                    "pp": "g",
                    "ps": "cqmv",
                    "p2": "fqnq",
                    "puid1": "woman",
                    "puid2": "16:17:18:19",
                    "puid3": "green"
                }
            }
        ]
    }
];
var userTimeout = 500;
window.YaHeaderBiddingSettings = {
    biddersMap: adfoxBiddersMap,
    adUnits: adUnits,
    timeout: userTimeout
};
</script>
<script src="https://yastatic.net/pcode/adfox/loader.js" crossorigin="anonymous"></script>

См. также пример заполнения параметров для монетизатора ADFOX в генераторе конфигурационного скрипта.

Что происходит в аккаунте монетизатора 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 в adUnitsПоддержка InPage videoПараметр площадки в params
CriteocriteoнетнетplacementId
Solowayadriverданет
HPMD (Happy Monday)hpmdнетнет
Buzzoolabuzzoolaнетда
MytargetmyTargetнетнет
Facebookfacebookданет
Between DigitalbetweenDigitalдада
All in One Mediaaioнетнет
GetIntentgetintentнетнет
Tinkofftinkoffнетнет
Videonowvideonowнетнет
RTB Housertbhouseнетнет
Relaprelapнетнет
Pladformpladformданет
Alfasensealfasenseдада
Fotostranafotostranaнетнет
Hybridhybridнетда
Mgidmgidданет
DGT SSPdgt_sspнетнет
ADSPENDadspendдада
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.

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

Если для контейнера используется функция перезагрузки кода (метод 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
    };
</script>
<script src="https://yastatic.net/pcode/adfox/loader.js" crossorigin="anonymous"></script>
</head>
<body>
<div id="adfox_1"></div>
<script>
    window.Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_1',
        params: {
            pp: 'g',
            ps: 'cnsf',
            p2: 'frnp'
        }
    });
</script>
<div id="adfox_2"></div>
<script>
    window.Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_2',
        params: {
            pp: 'g',
            ps: 'cnsh',
            p2: 'frnq'
        }
    });
</script>
<div id='adfox_3'></div>
<script>
    window.Ya.adfoxCode.create({
        ownerId: 255196,
        containerId: 'adfox_3',
        params: {
            pp: 'g',
            ps: 'cnsh',
            p2: 'frny'
        }
    });
</script>
</body>

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

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

Новый запрос к покупателям и его завершение вызовет этот 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.