ADFOX Sites Help

Код вставки

Виды кодов

Код вставки необходимо установить на сайт один раз, а всё управление рекламными кампаниями и баннерами осуществлять через интерфейс ADFOX.

Не рекомендуем вносить изменения в код вставки, так как это может нарушить его работоспособность.

Вид кода зависит от того, в каком типе представления создан тип баннера.


Рис1. Доступные виды кодов для каждого типа представления

Рассмотрим каждый вид кода:

Асинхронные коды с библиотекой loader.js

Асинхронные коды с библиотекой loader.js - это новый вид кодов в ADFOX.
Возможность получения кодов в интерфейсе подключается по запросу в службу технической поддержки.

Библиотека loader.js — это единая библиотека с автоматическим обновлением.
Мы объединили несколько библиотек для разных видов кодов в одну и разместили её на нашем сервере. При подключении нового кода вам всегда будет доступна последняя стабильная версия библиотеки.

Подключите один раз в head страницы библиотеку loader.js:

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

Далее из кодов вставок ссылку на библиотеку нужно удалять.

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

Асинхронный код вставки (NEW)

Управление загрузкой баннера:

window.Ya.adfoxCode.create(bannerOptions);

где bannerOptions:
ownerId — идентификатор аккаунта клиента;
containerId — идентификатор элемента, который является контейнером для баннера;
params — блок с параметрами запроса за баннером.

Пример асинхронного кода вставки:

<div id="adfox"></div>
<script>
    window.Ya.adfoxCode.create({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
            pt: 'b',
            p1: 'bsoji'
        }
    });
</script>

Для площадки на асинхронном коде можно использовать функцию перезагрузки баннера.

Асинхронный код с проверкой скролла (NEW)

Код вставки с проверкой скролла обычно используется на площадках во втором и ниже экранах.
Запрос за баннером будет отправлен только тогда, когда площадка с таким кодом вставки попадёт в область видимости на экране монитора посетителя сайта.

Управление загрузкой баннера:

window.Ya.adfoxCode.createScroll(bannerOptions);

где bannerOptions:
ownerId — идентификатор аккаунта клиента;
containerId — идентификатор элемента, который является контейнером для баннера;
params — блок с параметрами запроса за баннером.

Пример асинхронного кода с проверкой скролла:

<div id="adfox"></div>
<script>
    window.Ya.adfoxCode.createScroll({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
            pt: 'b',
            p1: 'bsoji'
        }
    });
</script>

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

Адаптивный код (NEW)

Сайт с адаптивной вёрсткой - это такой сайт, у которого есть стабильная верстка html и за её отображение на разных разрешениях экранов отвечают css стили.
Адаптивную вёрстку применяют для удобного просмотра сайта на различных устройствах: мобильных телефонах, планшетах и десктопах.

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

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

Управление загрузкой баннера:

window.Ya.adfoxCode.createAdaptive(bannerOptions, bannerStates, [adaptiveOptions]);

где bannerOptions:
ownerId — идентификатор аккаунта клиента;
containerId — идентификатор элемента, который является контейнером для баннера;
params — блок с параметрами запроса за баннером.

bannerStates:
desktop — загружать баннер, если открыта версия сайта для ноутбуков и компьютеров;
tablet — загружать баннер, если открыта версия сайта для планшетов;
phone — загружать баннер, если открыта версия сайта для мобильных телефонов/смартфонов.

В коде вставки обязательно наличие минимум 1 версии сайта.

adaptiveOptions:
tabletWidth — максимальная ширина в пикселях для версии "tablet". Значение по умолчанию: 830.
phoneWidth — максимальная ширина в пикселях для версии "phone". Значение по умолчанию: 480.
isAutoReloads — управление загрузкой баннеров при изменении размеров окна браузера без перезагрузки страницы:

  • true - баннер будет уничтожаться и заново загружаться с сервера;
  • false (по умолчанию) - баннер будет скрываться, но не будет уничтожаться в верстке, при возвращении размера пользователь будет видеть тот же баннер.

Пример адаптивного кода:

<div id="adfox-id"></div>
<script>
     // banner only for desktop and tablet 
    window.Ya.adfoxCode.createAdaptive({
        ownerId: 168627,
        containerId: 'adfox-id',
        params: {
            pp: 'g',
            ps: 'bnfx',
            p2: 'evbi'
        }
    }, ['desktop', 'tablet'], {
        tabletWidth: 1000,
        phoneWidth: 300,
        isAutoReloads: false
    } // states
);
</script>

Для площадки на адаптивном коде можно использовать функцию перезагрузки баннера.

Адаптивный код с проверкой скролла (NEW)

Управление загрузкой баннера:

window.Ya.adfoxCode.createScroll(bannerOptions, bannerStates, [adaptiveOptions]);

Расшифровку параметров см. в адаптивном виде кода.

Пример адаптивного кода с проверкой скролла:

<div id="adfox-id"></div>
<script>
     // banner only for desktop and tablet 
    window.Ya.adfoxCode.createScroll({
        ownerId: 168627,
        containerId: 'adfox-id',
        params: {
            pp: 'g',
            ps: 'bnfx',
            p2: 'evbi'
        }
    }, ['desktop', 'tablet'], {
        tabletWidth: 1000,
        phoneWidth: 300,
        isAutoReloads: false
    } // states
);
</script>

Для площадки на адаптивном коде с проверкой скролла можно использовать функцию перезагрузки баннера.

Public API

Все виды кодов с библиотекой loader.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 функции, которые были переданы в параметры баннера, будут выполнены заново.

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

Функция перезагрузки кода

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

Управление загрузкой баннеров:

    window.Ya.adfoxCode.reload(containerId);

где containerId — идентификатор элемента, который является контейнером для баннера.
Если требуется перезагрузка всех площадок, оставьте containerId пустым.

Пример вызова перезагрузки площадки с идентификатором контейнера "adfox-id"

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

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

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

onLoad

Вызывается, когда получен ответ за запрос и в ответе присутствует объект window.loadAdFoxBundle. Вызывается до onRender.
Аргументы callback onLoad:

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

onRender

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

onStub

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

onError

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

Тип ошибкиТипОписание
typeStringprocessBundleParams — указаны неверные параметры в коде вставки, баннер не будет показан.
adfoxBackend — сервер ADFOX вернул ошибку, баннер не будет показан.
userScriptError — код баннера содержит синтаксическую ошибку, возможность показа баннера зависит от ошибки.
messageStringТекст с описанием ошибки. В разных браузерах одна и та же ошибка может содержать разное сообщение, в том числе разной степени детализованности.

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

<script>
     window.Ya.adfoxCode.createScroll({
        ownerId: 208087,
        containerId: 'adfox',
        params: {
            pt: 'b',
            p1: 'bsoji'
        },
        onLoad: function(data) { /* some code */ },
        onRender: function() { /* some code */ },
        onError: function(error) { /* some code */ },
        onStub: function() { /* some code */ }
    });
</script>

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

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

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

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

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

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

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


Устаревшие виды кодов

Некоторые шаблоны баннеров и модули системы ADFOX работают только на видах кодов с библиотекой loader.js. Рекомендуем произвести замену кодов на сайте для получения максимальных возможностей по использованию системы ADFOX.

Синхронный код (устарел)

Синхронный код вставки генерируется для Стандартных типов баннеров.

На данный момент синхронный код является устаревшим видом и некоторые возможности ADFOX на этом виде кода не поддерживаются.

Рекомендуем перевести все синхронные площадки на асинхронные коды вставки. За подробностями обращайтесь в службу технической поддержки.

Пример синхронного кода вставки

Асинхронный код (устарел)

Асинхронный код вставки, требующий подключения дополнительных библиотек на сайт, является устаревшей версией и рекомендуется его заменить на асинхронный код без подключения отдельных библиотек.

Пример асинхронного кода вставки (устаревшая версия с подключением библиотеки)

Асинхронный код с проверкой скролла (устарел)

Асинхронный код с проверкой скролла, требующий подключения дополнительной библиотеки на сайт, является устаревшей версией и рекомендуется его заменить на асинхронный код с проверкой скролла без подключения отдельных библиотек.

Пример асинхронного кода вставки с проверкой скролла (устаревшая версия с подключением библиотеки)

XML код

Для площадок, созданных с XML-типами баннеров, в интерфейсе ADFOX генерируются ссылки для получения XML.

Пример ссылки для получения XML

https://ads.adfox.ru/166283/getCode?pp=g&ps=cgdy&p2=ewap&pfc=a&pfb=a&plp=a&pli=a&pop=a

Ссылка устанавливается в приложение или плеер и в ответ на запрос сервер ADFOX вернет XML-ответ.

В ADFOX существуют ссылки от баннера, с помощью которых можно посчитать клики, показы, события, а также получить sfw файл или изображение, загруженные в баннер.
Виды простых ссылок:
Ссылка для получения пиксела - используется для учета показов баннера.
Ссылка для перехода - используется для учета кликов, при вызове ссылки произойдет учет перехода на сайт рекламодателя и перенаправление пользователя по ссылке, указанной в баннере в параметре "URL перехода".
Чтобы получить ссылку для перехода нажмите на кнопку "Получить ссылку для перехода" и подтвердите, что согласны с отключением механизма антинакрутки.
Ссылка для получения Flash - в ответ на такую ссылку вернется swf файл, загруженный в баннер в поле "Flash-ролик".
Ссылка для получения изображения - в ответ на такую ссылку вернется изображение, загруженное в баннер в поле "Изображение".
Ссылка для вызова события - если в параметрах баннера была включена галка "События включены", то появляется возможность скопировать до 30 ссылок на события.

В ссылках необходимо заменить [RANDOM] у параметра pr на функцию рандомизации (генерации случайного целого числа в диапазоне от 1 до 4294967295 включительно).

Например, в ADFOX функция рандомизации %random%:
http://ads.adfox.ru/166283/getCode?p1=bnjwv&p2=elet&ptrc=b&pfc=bakej&pfb=dacud&pr=[RANDOM]
После замены получим ссылку:
http://ads.adfox.ru/166283/getCode?p1=bnjwv&p2=elet&ptrc=b&pfc=bakej&pfb=dacud&pr=%random%

Ссылки работают только в том случае, если баннер и РК активны и проходят по таргетированию и ограничениям.
Ссылки работают независимо друг от друга. Например, можно получить только кликовую ссылку, тогда у баннера не будет статистики по показам, но будут считаться клики.

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

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

Добавление параметров в код вставки производится либо в объект 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'
}

Синтаксис добавления для синхронных кодов, асинхронных кодов (устаревшая версия) и XML:

name=value&

Найдите строчку запроса к серверу ADFOX, например:

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

Например, добавим параметр eid1 со значением firstEid:

ads.adfox.ru/166283/prepareCode?pp=g&ps=cgdy&p2=evvv&pct=a&plp=a&pli=a&pop=a&pr=' + pr +'&pt=b&pd=' + addate.getDate() + '&pw=' + addate.getDay() + '&pv=' + addate.getHours() + '&prr=' + afReferrer + '&dl='+dl+'&pr1='+pr1'&eid1=firstEid

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

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

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

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

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