Возможности для кодов с loader.js

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

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

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) на странице для всех последующих запросов.

Срезы статистики для блоков 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.

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

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

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

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

Для этого необходимо выполнить два шага:

1. В строке подключения библиотеки добавьте атрибут async.

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

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>

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

  1. Дополнительные параметры
  2. Переопределение Referrer

Дополнительные параметры

Добавление параметров в код вставки производится либо в объект 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 - передается по умолчанию в кодах вставки с библиотекой loader.js. Если адрес в dl не передан, то будет использоваться значение из http-заголовка запроса.

ld - document.location.href - (приоритетнее, чем dl) подставьте в параметры запроса при необходимости переопределения значения referrer или dl.