Возможности кодов вставки

Перезагрузка кода

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

Вы можете управлять загрузкой баннеров с помощью параметров containerId и onlyIfWasVisible:

Ya.adfoxCode.reload(containerId, {onlyIfWasVisible: true});

Значения параметров:

  • containerId — идентификатор элемента, который является контейнером для баннера. Если требуется перезагрузка всех площадок, то вместо containerId укажите null;
  • onlyIfWasVisible — указывает на то, нужно ли проверять нахождение контейнера в видимой области экрана, чтобы произвести перезагрузку:
    • true — перезагрузка площадки/площадок, которые находятся в видимой области экрана у пользователя;
    • false или параметр отсутствует — перезагрузка производится для указанных контейнеров без учета нахождения в видимой области экрана.
Перезагрузка всех контейнеров в области видимости
Ya.adfoxCode.reload(null, {onlyIfWasVisible: true});
Перезагрузка одного конкретного контейнера (без учета нахождения в видимой области)
Ya.adfoxCode.reload(containerId, {onlyIfWasVisible: false});

или

Ya.adfoxCode.reload(containerId)
Пример вызова перезагрузки площадки с идентификатором контейнера adfox-id
<button onclick="Ya.adfoxCode.reload('adfox-id')">Reload</button>

Срезы статистики для блоков RTB

В том случае, если вы используете монетизацию, у вас есть возможность дополнительно задать в коде вставки Adfox идентификатор среза и собирать отдельную статистику по срезам.

Идентификатор среза задается в отдельной переменной:

Имя переменной Описание Тип данных
partner-stat-id Идентификатор среза Число от 1 до 1000000000

Задайте идентификатор среза в коде вызова рекламы в блоке params при размещении на сайте, например:

<div id="adfox_1485963383642980"></div>
<script>
  window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
      ownerId: 232598,
      containerId: 'adfox_1485963383642980',
      params: {
        p1: 'bufhf',
        p2: 'fbao',
        'partner-stat-id': '34567'
      }
    })
  })
</script>

Идентификатор среза в примере — 34567.

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

Показ полноэкранных баннеров в мобильной версии сайта

Ранее в Adfox можно было показывать полноэкранный баннер в мобильной версии сайта только в некоторых случаях:

  • в прямых продажах, используя шаблоны Fullscreen HTML5;
  • в рекламных кампаниях с Рекламной сетью Яндекса или другими монетизаторами, используя собственные обертки для показа сторонних баннеров на весь экран.

Теперь мы доработали возможность показа полноэкранного баннера в мобильной версии сайта: любые баннеры, в том числе сторонние коды, баннеры от Рекламной сети Яндекса или других монетизаторов, можно показывать на весь экран. При этом дополнительные обертки не нужны: все необходимые элементы полноэкранной рекламы (кнопка Закрыть, таймер обратного отсчета до закрытия и подложка) будут добавлены автоматически.


Как настроить показ полноэкранных баннеров
  1. В код вставки Adfox на нужной площадке добавьте параметр type: 'fullscreen'.
    Пример кода для показа баннера на весь экран
    window.yaContextCb.push(()=>{
      Ya.adfoxCode.create({
        ownerId: 264109,
        containerId: 'adfox_164750946031426465',
        type: 'fullscreen',
        params: {
          p1: 'cdvyr',
          p2: 'ghnb',
        }
      })
    })      
  2. Если на площадке есть прямые продажи, добавьте баннеры в рекламную кампанию по инструкции, используя нужные шаблоны.
  3. Если вы подключаете монетизацию с Рекламной сетью Яндекса, настройте параметры RTB-блока следующим образом:
    1. Выберите мобильную версию сайта.
    2. Укажите тип блока — Полноэкранный.
    3. Добавьте рекламные форматы: медийная реклама (баннеры), видеореклама или стандартный дизайн (текстово-графические объявления) — и выберите стратегию показа. Сохраните блок.
  4. Если вы подключаете внешнюю монетизацию через Header Bidding, настройте ее по инструкции.

  5. Если вы подключаете внешнего монетизатора Google, настройте его по инструкции. Рекомендуем использовать размеры баннеров шириной не менее 160 px и высотой не более 600 px.
  6. При необходимости установите ограничение по показам на уровне площадки. Частота показов будет действовать для всех кампаний, размещенных на площадке в Adfox: кампаний с прямыми продажами, Рекламной сети Яндекса и с использованием Header Bidding.

    В блоке Рекламной сети Яндекса, который создан в Adfox, частота показов задана по умолчанию, не изменяется и равна 1 показу в 5 минут для одного уникального пользователя.

  7. Чтобы узнать, в какой момент реклама была закрыта, добавьте callback-функцию onClose.

    Если пользователь закрыл рекламный блок, в ответ можно выполнить какое-либо действие, например, вызвать другой рекламный блок. Для этого впишите код с действием в onClose.

    Пример кода вызова рекламы с функцией onClose
    window.yaContextCb.push(function () {
          Ya.adfoxCode.create({
                containerId: 'adfox_112233445566',
                ownerId: 11223344,
                params: {
                      dl: 'https://my-cool-site.ru/',
                      p2: 'fkds',
                      pp: 'h',
                      ps: 'cmky'
                },
                type: 'fullscreen',
                onClose: () => {
                      // действие, выполняемое площадкой после закрытия баннера
                }
          });
    });
Особенности показа элементов полноэкранной рекламы
  • Баннеры, добавленные с помощью шаблонов Fullscreen HTML5, будут отрисованы на весь экран с элементами полноэкранной рекламы, указанными в параметрах этих баннеров.
  • Баннеры с другими шаблонами, в том числе сторонние коды, баннеры Рекламной сети Яндекса и внешних монетизаторов, тоже будут отрисованы на весь экран, а все элементы полноэкранной рекламы будут добавлены автоматически.

Показ Floor Ad в мобильной версии сайта

Вы можете добавить блок Floor Ad в мобильной версии сайта. В блоке можно показывать рекламу из Рекламной сети Яндекса и внешних монетизаторов, а также прямые продажи или собственное промо. При этом дополнительные обертки не нужны: все необходимые элементы рекламы Floor Ad (кнопка Закрыть, подложка) будут добавлены автоматически.

Блок появляется через 2 секунды после открытия страницы, фиксируется в нижней части экрана поверх содержимого сайта и занимает 100% ширины. Максимальная высота рекламы в блоке Floor Ad не должна превышать 30% высоты экрана, иначе рекламное объявление может обрезаться. Пользователь может закрыть рекламу в любой момент.


Как настроить показ Floor Ad
  1. В код вставки Adfox на нужной площадке добавьте параметр type: 'floorAd'.

    Пример кода для показа Floor Ad
    <div id="adfox_164750946031426465"></div>
    <script>
      window.yaContextCb.push(()=>{
        Ya.adfoxCode.create({
          ownerId: 264109,
          containerId: 'adfox_164750946031426465',
          type: 'floorAd',
          params: {
            p1: 'cdvyr',
            p2: 'ghnb',
          }
        })
      })
    </script>  
  2. Разместите полученный код на странице сайта между тегами <body> и </body>.

  3. Если вы подключаете монетизацию с Рекламной сетью Яндекса, настройте параметры RTB-блока следующим образом:

    1. Выберите мобильную версию сайта.
    2. Укажите тип блока — Floor Ad.
    3. Окно с выбором форматов вы можете пропустить: набор форматов в блоке Floor Ad предустановленный, его нельзя изменить. Подробнее о наборе форматов в блоке Floor Ad читайте в Справке Рекламной сети Яндекса.
    4. Выберите стратегию показа и сохраните блок.
  4. Если на площадке есть прямые продажи или собственные промо-кампании, добавьте баннеры по инструкции, используя шаблоны:

  5. Если вы подключаете внешнюю монетизацию через Header Bidding, настройте ее по инструкции.
  6. Если вы подключаете внешнего монетизатора Google, настройте его по инструкции.
    Важно. При подключении внешних монетизаторов, прямых продаж и промо-кампаний максимальная высота баннеров не должна превышать 30% от высоты экрана. Для блока Floor Ad рекомендуем использовать баннеры размеров 320 х 100, 320 х 50 пикселей.
  7. Чтобы узнать, в какой момент реклама была закрыта, добавьте callback-функцию onClose.

    Если пользователь закрыл рекламный блок, в ответ можно выполнить какое-либо действие, например, вызвать другой рекламный блок. Для этого впишите код с действием в onClose.

    Пример кода вызова рекламы с функцией onClose
    window.yaContextCb.push(function () {
          Ya.adfoxCode.create({
                containerId: 'adfox_112233445566',
                ownerId: 11223344,
                params: {
                      dl: 'https://my-cool-site.ru/',
                      p2: 'fkds',
                      pp: 'h',
                      ps: 'cmky'
                },
                type: 'floorAd',
                onClose: () => {
                      // действие, выполняемое площадкой после закрытия баннера
                }
          });
    });

Адаптация внешнего вида виджета под дизайн сайта

Вы можете динамически менять внешний вид рекомендательного виджета, созданного в Adfox, для разных разделов сайта или тем оформления (например, светлой или темной). Для этого добавьте в код вставки параметр additionalClasses и перечислите в нем массив классов, например:

<script>
  Ya.adfoxCode.create({
    ownerId: 208087,
    containerId: 'adfox',
    params: {
      p1: 'cmrtz',
      p2: 'gqqu',
      puid1: '',
      puid2: ''
    },
    insertionCodeParams: {
      additionalClasses: ['dark', 'light'],
    }
  });
</script>

Переопределение referer

Referer — адрес страницы сайта, с которой был отправлен запрос за баннером.

По умолчанию адрес страницы сайта передается в http-заголовках запроса и используется для определения разделов сайта и проверки таргетирования по URL.

Если в аккаунте подключен модуль "Переопределение referer", это означает, что адрес страницы сайта ожидается в параметре запроса dl или ld.

  • dl — document.location — передается по умолчанию в кодах вставки с библиотекой context.js. Если адрес в dl не передан, будет использоваться значение из http-заголовка запроса.
  • ld — document.location.href — (приоритетнее, чем dl) подставьте в параметры запроса при необходимости переопределения значения referer или dl.

Callback-функции в коде вставки

В кодах вставок для безразмерных типов баннеров есть возможность использования callback-функций:

onClose

Вызывается, когда пользователь закрыл рекламу. Функция доступна для полноэкранного блока и блока Floor Ad.

onError

Вызывается, если в ходе выполнения запроса была получена сетевая ошибка (например, 404) или же код баннера содержит синтаксическую ошибку.

Аргументы callback onError:

Тип ошибки Тип Описание
type String processBundleParams — указаны неверные параметры в коде вставки, баннер не будет показан.
adfoxBackend — сервер Adfox вернул ошибку, баннер не будет показан.
userScriptError — код баннера содержит синтаксическую ошибку, возможность показа баннера зависит от ошибки.
message String Текст с описанием ошибки. В разных браузерах одна и та же ошибка может содержать разное сообщение, в том числе разной степени детализованности.
onLoad

Вызывается, когда получен ответ за запрос и в ответе присутствует объект window.loadAdfoxBundle. Вызывается до onRender.

Аргументы callback onLoad:

Поле Тип Описание
data.bundleName String Выведет имя шаблона баннера (картинка, HTML-Creative и пр.).
data.bundleParams Object Выведет данные шаблона, на основе которых баннер будет отрисован.
onRender

Вызывается, когда код баннера или баннера по умолчанию (заданный пользователем) был вставлен в контейнер.

onStub

Вызывается, когда сервер вернул заглушку (системный код), контейнер остался пустым.

Пример использования callback-функций в коде вставки
<script>
     Ya.adfoxCode.createScroll({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
            pt: 'b',
            p1: 'bsoji'
        },
        onClose: () => { /* some code */ },
        onError: function(error) { /* some code */ },
        onLoad: function(data) { /* some code */ },
        onRender: function() { /* some code */ },
        onStub: function() { /* some code */ }
    });
</script>

Skip-токен для кода вставки

Если несколько кодов вставки Adfox на странице связаны с одним блоком Рекламной сети Яндекса, с большой вероятностью от Рекламной сети Яндекса придет одинаковая реклама.

Чтобы включить защиту от показа одинаковых объявлений, рекомендуем добавить в код вставки Adfox опцию sequentialLoading: true. Она включает последовательное обращение блоков Adfox за рекламой, что предотвращает показ дублей.

Примечание. Опция работает только с рекламой в Рекламной сети Яндекса и не затрагивает прямые продажи.
Пример использования skip-токена
window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
        ownerId: 411614,
        sequentialLoading: true,
        containerId: 'containerId-1',
        params: {
            p1: 'cvtzm',
            p2: 'hvob',        
        }
    })
})

Public API

Все виды кодов с библиотекой context.js для создания рекламного блока возвращают объект. Данный объект имеет 5 методов для управления:

  1. destroy — уничтожает баннер и очищает контейнер, в который была вставлена реклама.
  2. initialize — пересоздает баннер, уничтоженный методом "destroy". При вызове метода будет осуществлен запрос на сервер за рекламой. Если баннер не был уничтожен методом "destroy", ничего не произойдет.
  3. reload — перезагружает баннер. При этом идентификатор сессии (pr) не меняется. Фактически это скомбинированный вызов методов "destroy" и "initialize". Скрытые баннеры не перезагружаются — это связано с тем, что браузеры иногда некорректно рисуют баннеры в скрытых блоках. При вызове метода для скрытого баннера или для непроинициализированного баннера перезагрузка не произойдет.
  4. hide — скрывает баннер, не уничтожая его. Контейнер баннера становится скрытым с помощью стиля display: none.
  5. show — показывает скрытый баннер, убирая стиль display: none у контейнера. Запрос на сервер при этом не отправляется.

Public API отлично подходит для одностраничных приложений, для которых важен полный контроль над состоянием страницы. Public API позволяет предотвратить утечки памяти и не допускает выпадение ошибок при уничтожении баннеров. При использовании повторной инициализации все callback-функции, которые были переданы в параметры баннера, будут выполнены заново.

Метод Ya.adfoxCode.clearSession(); — служит для изменения идентификатора сессии (pr) на странице для всех последующих запросов.

Возможность синхронной загрузки библиотеки context.js

Коды вставки и библиотека context.js загружаются асинхронно.

При необходимости можно реализовать синхронную загрузку библиотеки context.js, но это может замедлить работу сайта.

Чтобы преобразовать код:

  1. В строке подключения библиотеки уберите атрибут async.
    <script src="https://yandex.ru/ads/system/context.js"></script>
  2. Измените все коды вставки, которые уже установлены на сайте. Все новые коды вставки тоже нужно будет поменять.

    Синхронный код вставки не использует очередь вызова yaContextCb, adfoxAsyncParams, adfoxAsyncParamsScroll и adfoxAsyncParamsAdaptive.

    Новый асинхронный код Старый асинхронный код Синхронный код
    <script>
      window.yaContextCb.push(()=>{
        Ya.adfoxCode.create({
          ownerId: 208087,
          containerId: 'adfox',
          params: {
            pt: 'b',
            p1: 'bsoji'
          }
        })
      })
    </script>
    <script>
    (function(w, n) {
        w[n] = w[n] || [];
        w[n].push({
            ownerId: 208087,
            containerId: 'adfox-id',
            params: {
                pt: 'b',
                p1: 'bsoji'
            }
        });
    })(window, 'adfoxAsyncParams');
    </script>
    <script>
      Ya.adfoxCode.create({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
          pt: 'b',
          p1: 'bsoji'
        }
      })
    </script>

Передача дополнительных параметров в коды вставок

Добавление параметров в код вставки производится либо в объект params (для асинхронных кодов), либо в строку запроса к серверу Adfox (для синхронных и XML кодов).

При подстановке значений к параметру pk кодировка значений не требуется.

Синтаксис добавления для асинхронных кодов

name: value,         
  • Если value является текстом, заключаем в одинарные кавычки.
  • Если value является именем переменной, оставляем без кавычек.

  • Если новый параметр добавляется последним, запятая в конце не нужна.

Пример 1. Добавление puid1 с одним значением и puid2 с несколькими значениями через разделитель — двоеточие

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                puid1: 'value1',
                puid2: 'value1:value2:value3:value4'
                }  

Пример 2. Добавление eid1 со значением firstEid

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                eid1: 'firstEid'
                }           

Пример 3. Добавление pk с одним ключевым словом

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'отлично',
                pke: '1'
                }          

Пример 4. Добавление pk с несколькими ключевыми словами через разделитель — пробел

params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'отлично вполне здорово великолепно',
                pke: '1'
                }           
Пример 5. Добавление pk с ключевой фразой. Ключевая фраза может быть передана только одна.
params: {
                pp: 'g',
                ps: 'bnfx',
                p2: 'evbi',
                pk: 'здорово великолепно',
                pke: '1'
                }