Код вставки

код вставки
07.11.2018
Асинхронні коди з бібліотекою loader.js
Асинхронний код вставки (NEW)
Асинхронний код з перевіркою скролла (NEW)
Адаптивний код (NEW)
Адаптивний код з перевіркою скролла (NEW)
Public API
Функція перезавантаження коду
Коди для розміщення сторінках AMP і Turbo
Callback функції в коді вставки
onLoad
onRender
onStub
onError
Можливість асинхронної завантаження бібліотеки loader.js
Зрізи статистики для блоків RTB
Застарілі види кодів
Синхронний код (застарів)
Асинхронний код (застарів)
Асинхронний код з перевіркою скролла (застарів)
XML код
прості посилання
Розширені можливості пошуку в коді вставки
перевизначення Referrer

Стаття була оновлена

07.11.2018

види кодів

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

Чи не рекомендуємо вносити зміни в код вставки, так як це може порушити його працездатність.

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

Розглянемо кожен вид коду:

Асинхронні коди з бібліотекою loader.js

Асинхронні коди з бібліотекою loader.js - це новий і рекомендований до використання вид кодів в ADFOX.

Бібліотека loader.js - це єдина бібліотека з автоматичним оновленням.
Ми об'єднали кілька бібліотек для різних видів кодів в одну і розмістили її на нашому сервері. При підключенні нового коду вам завжди буде доступна остання стабільна версія бібліотеки.

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

Далі з кодів вставок посилання на бібліотеку потрібно видаляти.

Примітка. Чи не рекомендуємо завантажувати бібліотеку і завантажувати її з власного сервера, таким чином ви не отримаєте централізовані поновлення бібліотеки, через що можливі помилки в роботі кодів.

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

Формат відповідей сервера ADFOX
Відповідь на запит за банером сервер ADFOX повертає в JSON форматі.

JSON-відповідь містить кілька об'єктів:

{ "Jsonapi": {...}}, "meta": {...}, "data": [...], "errors": [...]}

jsonapi - зведена інформація про версії і використовуваному протоколі.
meta - технічна інформація про сесії на сторінці і номері запиту.
data - містить інформацію (шаблон банера, всі параметри банера зі значеннями) про банері або банері за замовчуванням, обраного для показу.
Якщо ж об'єкт data порожній, то в errors міститиметься інформація з кодом помилки:
errors - сервер ADFOX на всі запити відповідає кодом "200ОК", а безпосередньо в JSON відповіді об'єкт errors розкриває код стану HTTP запиту в параметрі status.

Деякі змінні у відповіді можуть бути закодовані за допомогою base64. Щоб розкодувати отримане значення вручну, використовуйте сторінку-кодировщик .

Асинхронний код вставки (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);

Приклад асинхронного коду з перевіркою скролла:

<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]);

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>

Коди для розміщення сторінках AMP і Turbo

На сайтах з підтримкою технології AMP і Турбо-сторінках, можливо розміщення реклами за допомогою ADFOX.

При отриманні коду вставки інтерфейс автоматично запропонує відповідний для площадки Вид коду:
Асинхронний - для турбо-сторінок;
AMP - для AMP-сторінок. Обов'язково вкажіть значення для параметрів "Ширина" та "Висота"

Приклад отримання коду вставки виду "AMP"

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

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

onLoad

Викликається, коли отримано відповідь за запит і у відповіді присутній об'єкт window.loadAdFoxBundle. Викликається до onRender.
Аргументи callback onLoad:

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

onRender

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

onStub

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

onError

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

Тип помилки Тип Опис type String processBundleParams - вказані неправильні в коді вставки, банер не буде показаний. adfoxBackend - сервер ADFOX повернув помилку, банер не буде показаний. userScriptError - код банера містить синтаксичну помилку, можливість показу банера залежить від помилки. message String Текст з описом помилки. У різних браузерах одна і та ж помилка може містити різну повідомлення, в тому числі різного ступеня деталізованності.

Приклад використання 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>

Можливість асинхронної завантаження бібліотеки loader.js

Коди вставки з бібліотекою loader.js працюють асинхронно, але сама бібліотека loader.js завантажується синхронно.
Якщо для сайту це має критичне значення, то можливо реалізувати асинхронну завантаження і бібліотеки loader.js.

Для цього необхідно виконати два кроки:

1. У рядку підключення бібліотеки додайте атрибут async.

2. Змініть всі коди вставки, які вже встановлені на сайті і які будуть встановлюватися в майбутньому:

Асинхронний код вставки повинен виконуватися в конструкції

(Function (w, n) {w [n] = w [n] || []; w [n] .push ({// параметри}) (window, 'adfoxAsyncParams');

Приклад в таблиці:

Вихідний код Змінений код <div id = "adfox"> </ div> <script> window.Ya.adfoxCode.create ({ownerId: 208087, containerId: 'adfox', params: {pt: 'b', p1: ' bsoji '}}); </ Script> <div id = "adfox-id"> </ div> <script> (function (w, n) {w [n] = w [n] || []; w [n] .push ( {ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b', p1: 'bsoji'}});}) (window, 'adfoxAsyncParams'); </ Script>

Адаптивний код вставки повинен виконуватися в конструкції

(Function (w, n) {w [n] = w [n] || []; w [n] .push ([{// параметри]);}) (window, 'adfoxAsyncParamsAdaptive');

Приклад в таблиці:

Вихідний код Змінений код <div id = "adfox-id"> </ div> <script> window.Ya.adfoxCode.createAdaptive ({ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b' , p1: 'bsoji'}}, [ 'desktop', 'tablet'], {tabletWidth 1000, phoneWidth: 300, isAutoReloads: false}); </ Script> <div id = "adfox-id"> </ div> <script> (function (w, n) {w [n] = w [n] || []; w [n] .push ( [{ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b', p1: 'bsoji'}}, [ 'desktop', 'tablet'], {tabletWidth 1000, phoneWidth: 300, isAutoReloads: false}]);}) (window, 'adfoxAsyncParamsAdaptive'); </ Script>

Асинхронний і адаптивний зі скролл повинні виконуватися в конструкції

(Function (w, n) {w [n] = w [n] || []; w [n] .push ([{// параметри]);}) (window, 'adfoxAsyncParamsScroll');

Приклад в таблиці:

Вихідний асинхронний код з скролл Змінений код <div id = "adfox-id"> </ div> <script> window.Ya.adfoxCode.createScroll ({ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b', p1: 'bsoji'}}); </ Script> <div id = "adfox-id"> </ div> <script> (function (w, n) {w [n] = w [n] || []; w [n] .push ( [{ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b', p1: 'bsoji'}}]);}) (window, 'adfoxAsyncParamsScroll'); </ Script> Вихідний адаптивний код з скролл Змінений код <div id = "adfox-id"> </ div> <script> window.Ya.adfoxCode.createScroll ({ownerId: 208087, containerId: 'adfox-id', params : {pt: 'b', p1: 'bsoji'}}, [ 'desktop'], {tabletWidth: 640}); </ Script> <div id = "adfox-id"> </ div> <script> (function (w, n) {w [n] = w [n] || []; w [n] .push ( [{ownerId: 208087, containerId: 'adfox-id', params: {pt: 'b', p1: 'bsoji'}}, [ 'desktop'], {tabletWidth: 640}]);}) (window, 'adfoxAsyncParamsScroll'); </ 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.

Ru/166283/getCode?
Ru/166283/getCode?
Ru/166283/getCode?
Ru/166283/prepareCode?

Статьи

Код вставки - Допомога по ADFOX Sites