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

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

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

<button onclick="Ya.adfoxCode.reload('adfox-id')">Reload</button>

Срезы статистики для блоков Рекламной сети Яндекса

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

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

Задайте идентификатор среза в коде вызова рекламы в блоке 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.

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

Эксперименты над рекламой с Varioqub

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

Показ полноэкранных баннеров

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

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

1. В код вставки Adfox на нужной площадке добавьте параметры:

   • type: 'fullscreen';
   • platform: 'desktop' — для десктопной версии сайта;
   • platform: 'touch' — для мобильной версии сайта.
   Пример кода для показа баннера на весь экран

   <div id="adfox_164750946031426465"></div>
   <script>
     window.yaContextCb.push(()=>{
       Ya.adfoxCode.create({
         ownerId: 264109,
         containerId: 'adfox_164750946031426465',
         type: 'fullscreen',
         platform: 'touch',
         params: {
           p1: 'cdvyr',
           p2: 'ghnb',
         }
       })
     })
   </script> 
   

2. Если на площадке есть прямые продажи, добавьте баннеры в рекламную кампанию по инструкции, используя нужные шаблоны.

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

   1. Выберите мобильную версию сайта.
   2. Укажите тип блока — Полноэкранный.
   3. Добавьте рекламные форматы: медийная реклама (баннеры), видеореклама или стандартный дизайн (текстово-графические объявления) — и выберите стратегию показа. Сохраните блок.

4. Если вы подключаете внешнюю монетизацию через Header Bidding, настройте ее по инструкции.

5. Если вы подключаете внешнего монетизатора Google, настройте его по инструкции. Рекомендуем использовать размеры баннеров шириной не менее 160 px и высотой не более 600 px.

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

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

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, будут отрисованы на весь экран с элементами полноэкранной рекламы, указанными в параметрах этих баннеров.
• Баннеры с другими шаблонами, в том числе сторонние коды, баннеры Рекламной сети Яндекса и внешних монетизаторов, тоже будут отрисованы на весь экран, а все элементы полноэкранной рекламы будут добавлены автоматически.
• Код вставки Adfox по умолчанию добавляет на полноэкранный баннер подложку. Если Header Bidding монетизатор хочет отрисовать ее самостоятельно, он может отключить подложку на стороне кода Adfox.

Показ Floor Ad

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

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

Размеры блока зависят от версии сайта:

Подробнее о блоке читайте в Справке Рекламной сети Яндекса.

Как настроить показ Floor Ad

1. В код вставки Adfox на нужной площадке добавьте параметры:

   • type: 'floorAd';
   • platform: 'desktop' для десктопной версии сайта;
   • platform: 'touch' для мобильной версии сайта.
   
   
   Пример кода для показа Floor Ad на десктопе

   <div id="adfox_164750946031426465"></div>
   <script>
     window.yaContextCb.push(()=>{
       Ya.adfoxCode.create({
         ownerId: 264109,
         containerId: 'adfox_164750946031426465',
         type: 'floorAd',
         platform: 'desktop',
         params: {
           p1: 'cdvyr',
           p2: 'ghnb',
         }
       })
     })
   </script> 
   

2. Разместите полученный код на странице сайта между тегами <body> и </body>.

3. Чтобы на одной странице показывать Floor Ad для десктопных и мобильных устройств, добавьте код блока для каждой версии сайта последовательно.

   Для проверки версии сайта и вызова нужного блока вы можете добавить в код вставки метод Ya.adfoxCode.getPlatform().

   Пример вызова Floor Ad для десктопа и мобильных устройств

   <script>
     window.yaContextCb.push(() => {
         if (Ya.adfoxCode.getPlatform() === 'desktop') {
           // вызов FloorAd для десктопной версии
           Ya.adfoxCode.create({
             ownerId: 264109,
             containerId: 'adfox_164750946031426465',
             type: 'floorAd',
             platform: 'desktop',
               params: {
                 p1: 'cdvyr',
                 p2: 'ghnb',
               }
           });
         } else {
           // вызов FloorAd для мобильной версии
           Ya.adfoxCode.create({
             ownerId: 264109,
             containerId: 'adfox_164750946031426466',
             type: 'floorAd',
             platform: 'touch',
               params: {
                 p1: 'cdvyr',
                 p2: 'ghnb',
               }
           });
         }
     });
   </script>
   

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

   1. Выберите тип блока Floor Ad, укажите название и выберите платформу.
   2. Задайте настройки блока и при необходимости настройте рекламные форматы.

   Подробнее о настройке блока читайте в Справке Рекламной сети Яндекса.

5. Если на площадке есть прямые продажи или собственные промокампании, добавьте баннеры по инструкции, используя шаблоны:

   • Banner HTML5;
   • Banner Image;
   • InPage video;
   • Проброс кода;
   • Banner Slider;
   • Banner Video.

6. Если вы подключаете внешнюю монетизацию через Header Bidding, настройте ее по инструкции.

7. Если вы подключаете внешнего монетизатора Google, настройте его по инструкции.

   Важно

   При подключении внешних монетизаторов, прямых продаж и промокампаний максимальная высота баннеров не должна превышать:

   • В мобильной версии — 30% от высоты экрана. Рекомендуем использовать баннеры размером 320 × 100, 320 × 50 пикселей.
   • В десктопной версии — 90 пикселей.

Показ Top Ad

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

Блок Top Ad появляется через две секунды после открытия страницы и фиксируется в верхней части экрана поверх содержимого сайта. Пользователь может закрыть рекламу в любой момент.

Ширина блока равна длине короткой стороны экрана. Высота блока не превышает 100 пикселей. Объявления с большей высотой будут вписаны в блок с изменением размеров. Подробнее о блоке читайте в Справке Рекламной сети Яндекса.

Как настроить показ Top Ad

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

   Пример кода для показа Top Ad

   <div id="adfox_164750946031426465"></div>
   <script>
     window.yaContextCb.push(()=>{
       Ya.adfoxCode.create({
         ownerId: 264109,
         containerId: 'adfox_164750946031426465',
         type: 'topAd',
         params: {
           p1: 'cdvyr',
           p2: 'ghnb',
         }
       })
     })
   </script>  
   

2. Разместите полученный код на странице сайта между тегами <body> и </body>.

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

   1. Выберите тип блока Top Ad и укажите его название.
   2. Задайте настройки блока и при необходимости настройте рекламные форматы.

   Подробнее о настройке блока читайте в Справке Рекламной сети Яндекса.

4. Если на площадке есть прямые продажи или собственные промокампании, добавьте баннеры по инструкции, используя шаблоны:

   • Banner HTML5;
   • Banner Image;
   • Проброс кода;
   • Banner Slider.

5. Если вы подключаете внешнюю монетизацию через Header Bidding, настройте ее по инструкции.

6. Если вы подключаете внешнего монетизатора Google, настройте его по инструкции.

   Важно

   При подключении внешних монетизаторов, прямых продаж и промокампаний максимальная высота баннеров не должна превышать 100 пикселей. Рекомендуем использовать баннеры размеров 320 × 100, 320 × 50 пикселей.

Адаптация внешнего вида нативного блока под тему оформления сайта

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

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

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

Вы можете динамически менять внешний вид рекомендательного виджета, созданного в 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

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

onVideoEnd

Вызывается, когда рекламный ролик завершен. Функция доступна только для формата InPage-видео. После сворачивания плеера с InPage-видео выполнится альтернативный код, указанный в callback-функции.

Пример использования callback-функции onVideoEnd в коде вставки InPage

<script>
    window.Ya.adfoxCode.create({
        ownerId: 123456,
        containerId: 'banner-inpage',
        params: {
            p1: 'clxao',
            p2: 'gwfm',
            insertAfter: 'undefined',
            insertPosition: '0',
            stick: true,
            stickTo: 'auto',
            stickyColorScheme: 'light'
        },
        // Callback-функция с кодом вставки RTB-блока, который отрисовывается в тот же контейнер
        onVideoEnd: () => {
            Ya.Context.AdvManager.render({
                renderTo: "banner-inpage",
                blockId: "R-A-123456-1"
                }
            )
        }
    });
</script>

<script>
   window.yaContextCb.push(()=>{
        Ya.adfoxCode.create({
           ownerId: 208087,
           containerId: 'adfox',
           params: {
               pt: 'b',
               p1: 'bsoji'
           },
           onClose: () => { /* код */ },
           onError: function(error) { /* код */ },
           onLoad: function(data) { /* код */ },
           onRender: function() { /* код */ },
           onStub: function() { /* код */ }
       })
   })
</script>

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

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

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

window.yaContextCb.push(()=>{
    Ya.adfoxCode.create({
        ownerId: 411614,
        sequentialLoading: true,
        containerId: 'containerId-1',
        params: {
            p1: 'cvtzm',
            p2: 'hvob',
        }
    })
})

Public API

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

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

Public API отлично подходит для одностраничных приложений (single page application), для которых важен полный контроль над состоянием страницы. 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'
                }          

Обратиться в службу поддержки

Написать в чат

Написать письмо