Инструкция по интеграции рекламодателей с партнёрской сетью LeadTrade

ОБЩИЙ ПРИНЦИП РАБОТЫ

Описанная ниже схема работы состоит из трёх частей и подходит для большинства кампаний. Типовой пример – работа с интернет-магазином. Несмотря на это, кампании могут иметь индивидуальные особенности или технические ограничения.

Интеграция состоит из трёх основных частей:

1. Обработка перехода из сети LeadTrade на сайт рекламодателя
2. Извещение сети LeadTrade о совершённом действии
3. Извещение сети LeadTrade об изменении статуса по совершённому ранее действию.

Ниже подробно описывается каждая часть.

ОБРАБОТКА ПЕРЕХОДА. ОПИСАНИЕ ПАРАМЕТРОВ, ПЕРЕДАВАЕМЫХ СЕТЬЮ LEADTRADE.

Сеть LeadTrade доставляет переходы на сайт рекламодателя, добавляя в исходную ссылку параметры, необходимые для последующем извещении о действии на странице действия.

Пример такой ссылки:

http://e-shop.ru/catalog/page?product=12345&promo=1&source=leadtrade&ltsource=12345 &lttracking=0000-0000-0000-0000-0000&ltpostclick=1363448720

Описание параметров:

• source = leadtrade, информационный параметр, который сообщает сайту рекламодателя что переход произошёл с сети LeadTrade.
  
  
• ltsource = <номер источника>, информационный параметр содержащий номер источника в сети LeadTrade. Данный параметр позволяет принимать решения об известных номерах источников на стороне сайта рекламодателя и производить учёт поступающих переходов в системах анализа, например в Google Analytics.
  
  
• lttracking = 0000-0000-0000-0000-0000. Идентификатор перехода, наиболее важный параметр. Данный параметр необходимо в последствии передать для корректного извещения сети LeadTrade о совершённом действии.
  
  
• ltpostclick = <timestamp для postclick>. Время в формате Unix Timestamp (количество секунд с 1970-01-01 00:00:00). Информационный параметр, указывающий сайту рекламодателя, до какой даты/времени будет активен идентификатор перехода.
  
  

Идентификаторы перехода, обозначенные нулями в примере представляются буквенно-цифровыми последовательностями. Максимальная длина – 50 символов.

Пример идентификатора перехода: a29f85da-5a349643-522f71cf-727dd424 

ОБРАБОТКА ПЕРЕХОДА. ОБРАБОТКА НА САЙТЕ РЕКЛАМОДАТЕЛЯ

Приём и разбор передаваемых GET-параметров должен осуществляться на любой странице сайта рекламодателя (а не только на главной или ограниченном наборе), так как вебмастера могут добавлять в систему LeadTrade ссылки на произвольные страницы сайта рекламодателя.

После приёма пользователя с указанными параметрами на сайте рекламодателя, ему необходимо установить cookie c именем lttracking и значением идентификатора перехода:

lttracking =0000-0000-0000-0000-0000

Время жизни установленной cookie должно соответствовать периоду Post-Click, указанному при регистрации кампании (оффера). Например, если Post-Click период равен 30 дням, то cookie должны действовать до времени, которое является суммой даты перехода плюс 30 дней.

Сеть LeadTrade на постоянной основе производит автоматический контроль за правильностью установки cookie (верное имя, значение и срок действия).

Помимо cookie, сайт рекламодателя может сохранять полученные во время перехода от сети LeadTrade параметры в своих внутренних системах (БД, профиле пользователя и прочее), однако установка cookie обязательна. 

ИЗВЕЩЕНИЕ О ДЕЙСТВИИ

Для информирования сети LeadTrade о действии, совершённом на сайте рекламодателя, применяется трекинг-пиксель (далее – пиксель). Простыми словами, в момент совершения действия, в код отображаемой пользователю страницы, подставляется код, загружающий с сервера LeadTrade прозрачное изображение размером 1х1 пиксель.

Это изображение не показывается пользователю, а служит средством выполнения запроса к серверу LeadTrade с передачей необходимых параметров.

Код пикселя с передачей параметров выглядит так:

<img src=”http://t.leadtrade.ru/<код оффера>.png?lttracking=0000-0000-0000-0000-0000&ltid=NNNNN&ltamount=NNN.NN" width="1px" height="1px" />

Описание параметров:

• <код оффера>.png – обязательное значение. <код оффера>, числовое значение должен быть заменён на код оффера в сети LeadTrade. Его вы можете получить в примерах кодов интеграции при просмотре страницы «Мои офферы» или уточнить у вашего менеджера
  
  
• lttracking=<трекинг-код> - обязательное значение. Идентификатор перехода, то же самое значение, которое было передано на этапе обработки перехода в виде 0000-0000-0000-0000-0000. Это значение необходимо получать из ранее установленной cookie.
  
  
• ltid=<идентификатор действия>. Обязательный параметр, должен содержать уникальный идентификатор действия, например номер заказа.
  
  
• ltamount = <сумма сделки в руб.коп>. Является обязательным параметров для офферов, работающих за процент с продаж. Разделителем является точка.
  
  

Параметр ltid является обязательным и показывается затем рекламодателю в списке его продаж. Идентификатором может являться, например:

• номер заказа
• номер заявки
• идентификатор пользователя
• номер платежа
• идентификатор созданного объекта в системе рекламодателя
  
  

Идентификатором может являться любая буквенно-цифровая последовательность символов, со знаками препинания, но без пробелов. Максимальная длина идентификатора – 200 символов.

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

Суммой сделки может являться, например:

• сумма заказа/покупки
• сумма платежа
• сумма пополнения счёта

Суммой должно являться число с дробной частью. Разделителем целой и дробной части должна являться точка, максимальное количество знаков после точки – 2.

Пример пикселя при работе за фиксированную цену:

<img src="http://t.leadtrade.ru/17.png?lttracking=0000-0000-0000-0000&ltid=14526-BIS" width="1px" height="1px" />

Пример пикселя, при работе за процент:

<img src=” http://t.leadtrade.ru/17.png?lttracking=0000-0000-0000-0000&ltid=14526-BIS&ltamount=140.27" width="1px" height="1px" />

 

ИЗВЕЩЕНИЯ О ДЕЙСТВИИ С КОДОМ ПРОТЕКЦИИ

 

Документация в разработке

 

ДОПОЛНИТЕЛЬНЫЕ ВОЗМОЖНОСТИ

 

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

Рекламодатель на странице «Мои офферы» может получить примеры интеграционных кодов, написанных на PHP и JavaScript, а также выставить режим работы: простой или с кодом протекции.

Для этого необходимо нажать в колонке «Коды интеграции» ссылку «Показать».

 

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

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

Пример:

<img src=” http://t.leadtrade.ru/0.png?lttracking=0000-0000-0000-0000ltid=NNNN custom_city=New-York&custom_site_time=270-seconds" width="1px" height="1px" />

Будут отображены в информации о продаже как

• city : New-York
• site_time : 270-seconds

Ограничения на формат передаваемых значений тот же, что и для идентификатора действия: число-буквенные последовательности без пробелов, длина до 200 символов.

JavaScript-пиксель

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

<script language="JavaScript" type="text/javascript">
var ltoffer     = 17;
var ltid        = escape('ORDER_ID');
var ltamount    = 0000.00;
var lttracking ='00000000-00000000-00000000-00000000';
</script>

<script language="JavaScript" type="text/javascript" src="http://t.leadtrade.ru/ltpixel.js"></script>

Где:

• ltoffer–код оффера, аналогичный параметру <код оффера>.png в обычном пикселе.
• ltid – идентификатор действия
• ltamount–суммасделки в рублях при работе за процент.
• lttracking – трекинг код, взятый из cookie.
  
  

Server-to-server запрос

Если не имеется технической возможности подставить код пикселя в код страницы, отображаемой пользователю, то возможен вызов URL пикселя с сервера.

Вызов из Adobe Flash

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

var loader:Loader = new Loader();
loader.load(new URLRequest(' http://t.leadtrade.ru/NNNN.png?lttracking=0000-0000-0000-0000&ltid=NNNNNNNN '));

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

ИЗВЕЩЕНИЕ О СТАТУСЕ ДЕЙСТВИЯ. XML протокол

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

От сети Leadtrade может исходить два вида запросов: со списком идентификаторов и за дату. Периодичность запросов и их точное время определяются внутренними настройками. Для осуществления запросов рекламодатель должен предоставить адрес страницы (скрипта) на сайте, к которой будет производиться запрос с отправкой данных. Данные отправляются методом POST. Кодировка – UTF-8. Запрос содержит три параметра:

xml – содержимое запроса в формате XML

pass – md5-хеш от установленного пароля (необязательный параметр, пароль согласуется с менеджером)

date – дата (формат ГГГГ-ММ-ДД ЧЧ:ММ:СС)

Если обеспечение безопасности при передаче данных не критично, то пароль можно не использовать.

Запрос со списком идентификаторов:

XML-запрос содержит в своём составе идентификаторы, полученные при вызове пикселя в параметре ltid. Количество идентификаторов в одном запросе не ограничено. Пример запроса:

<?xml version="1.0" encoding="UTF-8"?>
<items>
<item>10000001</item>
<item>10000002</item>
<item>10000003</item>
<item>10000005</item>
</items>

В ответ на такой запрос скрипт на стороне рекламодателя должен сформировать ответ, содержащий детальную информацию о запрашиваемых действиях. Формат ответа должен содержать следующие теги внутри контейнера item:

id – идентификатор действия (аналог параметра ltid, полученного пикселем)

status – статус действия (1, 2 или 3 – см. ниже)

На каждый переданный в запросе идентификатор в ответе должен присутствовать отдельный контейнер item. Пример ответа, содержащего ответ по одному идентификатору:

<?xml version="1.0" encoding="UTF-8"?>
<items>
<item>
<id>10000001</id>
<status>1</status>
</item>
</items>

Для поля status используются следующие числовые обозначения статусов:

1 – действие «принято» (будет оплачено впоследствии рекламодателем)

2 – действие «в обработке» (решение по нему ещё не принято, необходимо запросить статус позже)

3 – действие «отклонено» (действие не будет оплачено рекламодателем)

4 – запрошенное действие «не существует» (в запросе пришёл идентификатор, который не зафиксирован на сайте рекламодателя)

Статусы 1 и 3 являются терминальными статусами, то есть переход из этих статусов в какой либо другой впоследствии невозможен. Если сервер Leadtrade получил по идентификатору статус 1 или 3, он не будет повторять попытки запроса этого идентификатора когда-либо позже. Этот статус будет зафиксирован в Leadtrade окончательно, поэтому статусы 1 и 3 стоит отдавать только в том случае, если решение относительно действия принято окончательно.

Статусы 2 и 4 не являются терминальными. Сервер Leadtrade может периодически повторять попытки запроса соотвествующих идентификаторов, пока не будет получен один из терминальных статусов (1 или 3), либо до тех пор, пока не истечёт период ожидания (не оговаривается и является внутренней настройкой в сети Leadtrade).

Запрос за дату:

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

В случае любой непредвиденной ошибки в запросе (неверный пароль, некорректный формат XML и прочее) необходимо вернуть тег error, содержащий произвольное, но содержательное сообщение об ошибке. Например:

<?xml version="1.0" encoding="UTF-8"?> <error>Неверный пароль</error>

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

•  – Рекламодатель пополняет счет для оплаты вознаграждения Вебмастеру за лиды либо по предоплате(депозиту), либо по постоплате на основе договора.
•  – Рекламодатель получает на свой баланс оплаченные им средства за вычетом комиссий платежной системы.
•  – Рекламодатель имеет право пополнять счет с личного или корпоративного электронного кошелька, пластиковой карты, банковского счета или телефона.
•  – Возврат предоплаты(депозита) осуществляется, если не было активностей со стороны Вебмастеров. В противном случае депозит не возвращается, а остаётся на балансе в кабинете рекламодателя. Средства на балансе рекламодатель вправе открутить на лиды по любым другим офферам в системе Leadtrade.ru