Header Bidding

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

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

    Как работает Header Bidding:
    1. В момент загрузки страницы сайта пользователем специальный код Header_bidding.js одновременно отправляет запросы всем подключенным покупателям и они конкурируют за показ на единых условиях, делая свои ставки.
    2. Все ставки от покупателей приходят к серверу ADFOX вместе с рекламным запросом и сравниваются с CPM других кампаний вида Динамическая монетизация (если такие имеются в аккаунте издателя). Выбирается кампания с максимальной ставкой.
    3. Кампания с максимальной ставкой перевзвешивается с Рекламной сетью Яндекса для выбора победителя:
      1. Если РСЯ предлагает ставку больше, то РСЯ побеждает и получает право показать свою рекламу.
      2. Если РСЯ не может предложить ставку больше или отказывается от участия в торгах, то побеждает рекламная кампания с максимальной ставкой и получает право показать свой баннер.
    Преимущества использования Header Bidding для издателя:
    • удобный способ подключения внешних монетизаторов;
    • увеличение эффективности за счет учета ставок внешних монетизаторов в рамках ДМ;
    • снижение потерь трафика при схеме классических "водопадов";
    • сокращение времени для отрисовки рекламы за счет исключения "лишних" звеньев из водопада.
    Список покупателей
    • Criteo (в том числе с нативной рекламой)
    • Soloway
    • HPMD (Happy Monday)
    • Buzzoola
    • Mytarget
    • Videonow
    • Facebook
    • Between Digital
    • All in One Media
    • GetIntent
    • Tinkoff
    • RTB House
    • Relap
    • Pladform
    • IMHO (ADFOX)
    • ADFOX HB

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

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

    • в типе баннера шаблон для монетизатора N;
    • рекламная кампания, в параметрах которой указан внешний монетизатор N;
    • баннер в рекламной кампании, созданный с шаблоном монетизатора N;
    • на сайте должен быть скрипт с настройками для запросов ставок от площадок к монетизатору N.

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

    1. Определите типы баннеров, на которых будет происходить размещение покупателей. При необходимости создайте новые типы баннеров.
    2. К типам баннеров добавьте шаблоны для внешних монетизаторов header bidding:
      1. Перейдите в меню Настройки → Типы баннеров → Собственные → Безразмерные и кликните .
      2. Нажмите Использовать предзаданный и добавьте в тип баннера шаблоны для покупателей, которые именуются так:
        Header Bidding {название покупателя} [loader]
    3. Определите площадки для размещения покупателей и при необходимости создайте новые площадки.
    4. Для каждого покупателя добавьте одну рекламную кампанию и в параметре Внешний монетизатор укажите покупателя. Для всех монетизаторов, кроме IMHO (ADFOX) и ADFOX HB, значение CPM указывать не нужно, сервер получит его из ставки монетизатора и будет учитывать при выборе максимальной ставки среди всех кампаний уровня ДМ.

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

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

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

    6. Скопируйте идентификаторы (ID) созданных кампаний, они необходимы будут для дальнейших шагов по настройке конфигурационного скрипта на сайте.
      Как получить ID кампании
      ID кампании отображается рядом с ее названием на странице со всеми кампаниями.
    7. На сайте издателя все площадки, участвующие в Header Bidding, должны использовать коды вставки с библиотекой loader.js.

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

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

    Для подключения к монетизатору-клиенту ADFOX, издателю нужно:
    • заключить договор с монетизатором;
    • запросить код вставки ADFOX из аккаунта монетизатора.
    1. В аккаунте издателю необходимо произвести настройки под монетизатора, описанные в разделе Настройка аккаунта ADFOX, а именно:
      1. Определить типы баннеров и площадки, на которых будет происходить размещение монетизаторов.
      2. В типы баннеров, которые используются для площадок из п.1, добавить предзаданный шаблон для монетизатора ADFOX: Header Bidding ADFOX [loader].
      3. Добавить рекламную кампанию, выбрав монетизатора ADFOX HB и указать:
        • owner_id — идентификатор аккаунта монетизатора. Узнать его можно от монетизатора или из кода вставки монетизатора, например:

        • CPM — CPM порог для монетизатора (для монетизатора ADFOX ставка указывается в параметрах кампании. Остальные Header Bidding монетизаторы делают свои ставки при получении запроса со страницы сайта).
      4. Добавить баннер в рекламную кампанию с монетизатором.
    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 в своем аккаунте может работать в обычном режиме.

    В ходе запроса рекламы от площадки издателя, в аккаунте монетизатора выбор будет проходить по кампаниям:
    • с видом Гарантия;
    • прямых продаж с видом Динамическая монетизация;
    • с видом Промо.
    Исключаются из выбора кампании:
    • Сделки;
    • с видом "Динамическая монетизация":
      • Монетизация РСЯ;
      • Кампании внешних монетизаторов.

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

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

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

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

    Скопируйте полученный скрипт и разместите его в HEADсайта.

    Инструкция по созданию скрипта вручную:
    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 Параметр площадки в params
    Criteo criteo нет placementId
    Soloway adriver да
    HPMD hpmd нет
    Buzzoola buzzoola нет
    Mytarget myTarget нет
    Facebook facebook да
    Between Digital betweenDigital да
    All in One Media aio нет
    GetIntent getintent нет
    Tinkoff tinkoff нет
    Videonow videonow нет
    RTB House rtbhouse нет
    Relap relap нет
    Pladform pladform да
    Alfadart alfadart да
    Fotostrana fotostrana нет
    IMHO (ADFOX) adfox_imho-banners нет переменные из объекта params кода вставки монетизатора
    ADFOX HB adfox_{owner_name}, где {owner_name} — название аккаунта-монетизатора нет переменные из объекта params кода вставки монетизатора

    ID среза автоматически подставляется к запросу и дает возможность собирать отдельную статистику по срезам в Партнерском интерфейсе.

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

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

    • в любом месте страницы асинхронно добавьте скрипт 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>
    Рисунок 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
        };
    </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), как и в нашем примере, используется вызов функции, то она должна быть объявлена в глобальной области видимости.

    Пример конфигурационного скрипта с нативной рекламой
    const 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();
    Рисунок 2. Пример вызова метода в консоли браузера
    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 Биддер прислал корректный ответ без статуса.