Технические условия подключения

Введение

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

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

Как это работает?

Существуют две типовые схемы работы:

  1. CPL - учет конверсий и их оплата осуществляется в момент срабатывания трекинг-пикселя.
  2. CPS - учет конверсий осуществляется через трекинг-пиксель, оплата производится после подтверждения действия рекламодателем.

Интеграция включает в себя следующие элементы:

  1. Обработка перехода через клик-систему сети на сайт рекламодателя.
  2. Уведомление сети рекламодателем о выполнении действия.
  3. Уведомление сети рекламодателем об изменении статуса действия (для CPS-схемы).

1. Формирование ссылки для перехода через клик-систему

Рекламодатель предоставляет URL-адрес для перехода на сайт, который должен принимать дополнительные метки для учета различных параметров.

Рекламная сеть может передавать в ссылке следующие данные:

  • {NETWORK} — Идентификатор сети (в формате, удобном рекламодателю);
  • {SOURCE} — Идентификатор источника трафика;
  • {TID} — Идентификатор перехода (клика);

Если веб-сайт использует стандартные метки UTM - лучше использовать их. Если UTM не используется, необходимо реализовать учет других меток для всех страниц сайта.

Например, ссылка для перехода (ID источника = 555, ID перехода = 888) может иметь следующий вид:

http://advertiser.ru/?utm_source=exelo&utm_medium=cpa&utm_campaign=555&utm_term=888
http://advertiser.ru/?from=exelo&source=555&tid=888

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

2. Обработка перехода на стороне сайта рекламодателя

После перехода посетителя на сайт рекламодателя скрипт, обрабатывающий значения меток в URL-адресе, должен создать файлы Cookie с значениями, полученными в метках ссылки.

Время жизни файлов Cookie должно соответствовать периоду PostClick, устанавливаемому в правилах программы в рекламной сети.

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

3. Уведомление о выполнении действия

Существует 3 способа уведомления о выполнении действий:

  • Размещение JavaScript кода трекинг-пикселя на странице фиксации действия.
  • Размещение прозрачного изображения 1x1 (пикселя) на странице фиксации действия.
  • Осуществление серверного запроса методом GET или POST в момент фиксации действия.

Рекламодатель самостоятельно выбирает более приемлемый для него способ.

Каждый из вариантов реализует функцию обращения к трекинг-серверу Рекламной Сети для уведомления о выполнении действий.

Каждый из вариантов работает как по http так и по https (защищенному) протоколу.

Рекламодатель подставляет в код пикселя следующие данные:

  • {PIXEL_ID} - идентификатор пикселя обязательно (выдается рекламной сетью при добавлении программы)
  • {ITEM_ID} - идентификатор действия обязательно (id регистрации, id заказа)
  • {TID} - идентификатор клика/перехода опционально (передается в метке, генерируется на стороне сети)
  • {PRICE} - вознаграждение опционально (для программ с оплатой процента с покупки)
  • {ADDITIVE_INFO} - дополнительная информация опционально
  • {IP} - ip адрес посетителя опционально, для POSTBACK-запроса
  • {UAG} - user-agent (идентификатор браузера) опционально, для POSTBACK-запроса

Пример JavaScript-пикселя:

<script type="text/javascript">
(function() {
    var x_order = '{ITEM_ID}';
    var x_price = '{PRICE}';
    var x_infos = '{ADDITIVE_INFO}';
    var x_pixel = '{PIXEL_ID}';
    var xlo = document.createElement('script');
    xlo.type = 'text/javascript';
    xlo.async = true;
    xlo.src = '//track.exelo.ru/pixel.js?p='+x_pixel+'&o='+x_order+'&s='+x_price+'&i='+x_infos;
    var firstscript = document.getElementsByTagName('script')[0];
    firstscript.parentNode.insertBefore(xlo,firstscript);
})();
</script>

Пример IMG-пикселя:

<img src="//track.exelo.ru/pixel.gif?p={PIXEL_ID}&o={ITEM_ID}&i={ADDITIVE_INFO}&s={PRICE}" width="1" height="1" />

Пример POSTBACK-запроса с передачей TID (идентификатора перехода):

Если нет технических ограничений на запись идентификатора клика {TID}, то используется следующий запрос:

file_get_contents('//track.exelo.ru/?p='{PIXEL_ID}'&o='{ITEM_ID}'&i='{ADDITIVE_INFO}'&t='{TID}');

Если технической возможности передать идентификатора клика {TID} нет, тогда используется вариант с передачей IP и USER_AGENT пользователя.

file_get_contents('//track.exelo.ru/?p='{PIXEL_ID}'&o='{ITEM_ID}'&i='{ADDITIVE_INFO}'&ip='{IP}'&uag='{UAG}');

4. Обновление статусов действий

Срабатывание трекинг-пикселя (п.3) сообщает сети о выполнении действия.

Если программа работает по модели CPS (продажа, подтвержденный заказ и тп), то после фиксации действий им присваивается статус "Ожидает".

Обновление статусов действий в сети возможно 2 способами:

  1. Автоматический обмен данными в формате XML (XML-шлюз).
  2. POSTBACK-запрос с сервера рекламодателя

4.1. Обновление статусов действий: XML-шлюз

Сеть может отправлять 2 вида запросов:

  • за временной промежуток (дата от, дата до)
  • со списком номеров заказов ({ITEM_ID})

Запросы отправляются на url-адрес рекламодателя, который обрабатывает входящий POST-запрос и формирует ответ, содержащий статусы действий.

Пример запроса за промежуток времени

$_POST['from']='exelo';
$_POST['pass']='c549ff8e1f46306feeb2d3a1b58dfb5f';
$_POST['date_from']='26.10.2013';
$_POST['date_from']='28.10.2013';

Пример запроса с указанием id ({ITEM_ID}) действий

$_POST['from']='exelo';
$_POST['pass']='c549ff8e1f46306feeb2d3a1b58dfb5f';
$_POST['xml']=<<<EOF
<?xml version="1.0" encoding="UTF-8"?>
<items>
    <item>
1001</item>
    <item>
1002</item>
    <item>
1003</item>
    <item>
1004</item>
</items>
EOF;

Сервер рекламодателя должен вернуть ответ в формате XML следующего вида:

Пример ответа XML-шлюза

<?xml version="1.0" encoding="UTF-8"?>
<items>
    <item>
        <id>1001</id>
        <status>1</status>
        <tid>555001</tid>
        <price>725.45</price>
        <info>Apple Iphone 5S</info>
    </item>
    <item>
        <id>1002</id>
        <status>2</status>
        <tid>555002</tid>
        <price>465.20</price>
        <info>Apple Ipad Mini Black</info>
    </item>
    <item>
        <id>1003</id>
        <status>3</status>
        <tid>555003</tid>
        <price>1254.14</price>
        <info>Apple IMac 27'</info>
    </item>
    <item>
        <id>1004</id>
        <status>4</status>
        <tid></tid>
        <price></price>
        <info>заказ не найден</info>
    </item>
</items>

Описание возвращаемых данных:

id - идентификатор действия (id заявки, пользователя, покупки).

status - статус действия. Возможен один из 4 статусов для каждого действия:

  1. - Принято (действие одобрено рекламодателем: заказ оплачен, заявка подтверждена);
  2. - Ожидает (статус по-умолчанию - действие ожидает изменения статуса);
  3. - Отклонено (действие отклонено: отказ от оплаты, абонент не подтвердил заказ);
  4. - Ошибка (заказа с запрошенным ID не существует);

tid - идентификатор перехода. Необходим при ответе за запрос за временной промежуток.

price - сумма покупки или вознаграждения сети. Необходима если рекламодатель оплачивает процент с продажи.

info - дополнительная информация: название товара, причина отказа (в случае отмены действия).

4.2. Обновление статусов действий: POSTBACK-запрос

Данный режим подтверждения позволяет изменять статусы действий в режиме реального времени.

Запрос для подтверждения действия:

file_get_contents('//track.exelo.ru/?p='{PIXEL_ID}'&o='{ITEM_ID}'&k='{SECRET_KEY}'&a='accept');

Запрос для отклонения действия:

file_get_contents('//track.exelo.ru/?p='{PIXEL_ID}'&o='{ITEM_ID}'&k='{SECRET_KEY}'&a='decline');

Рекламодатель подставляет в код пикселя следующие данные:

  • {PIXEL_ID} - идентификатор пикселя обязательно (выдается рекламной сетью при добавлении программы)
  • {ITEM_ID} - идентификатор действия обязательно (id регистрации, id заказа)
  • {SECRET_KEY} - ключ для доступа к POSTBACK-API обязательно (выдается рекламной сетью при добавлении программы)