Интеграция с помощью XML-файла

Интеграция — процесс, в рамках которого вы настраиваете отправку данных о целевых действиях на вашем сайте в систему Admitad.

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

Общая информация: особенности и рекомендации

Приступить к интеграции можно только, если в вашей программе:
- уже сформирована трекинг-ссылка в разделе «Общие настройки»;
- уже добавлено целевое действие и настроен тариф для него в разделе «Действия».

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

Интеграция — обязательный этап для продолжения работы. Без нее невозможно запустить партнерскую программу в Admitad.
Чтобы ускорить интеграцию, рекомендуем привлечь к ее выполнению вашего собственного технического специалиста и передать ему эту инструкцию.

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

Что такое интеграция с помощью XML-файла и как она работает

Интеграция с помощью XML-файла — это способ интеграции вашего сайта с системой Admitad, для которого вам нужно создать на своем сервере XML-файл определенной структуры, куда будут выгружаться данные о действиях пользователей на вашем сайте.

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

Чтобы XML-файл могли просматривать только специалисты Admitad, вы можете ограничить доступ к этому файлу. Например, с помощью логина и пароля или путем указания IP-адреса сервера Admitad.

Рекомендуется настроить как можно более частую выгрузку информации в XML-файл, чтобы:

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

О других способах интеграции см. в статье «Выбор способа интеграции».

Как выполнить интеграцию с помощью XML-файла

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

настройте запись значения параметра admitad_uid в cookie;
настройте дедупликацию целевых действий;
подготовьте XML-файл;
протестируйте настроенную интеграцию.

Если кроме веб-версии сайта у вас есть мобильная версия сайта и/или форма быстрого заказа или заказа в 1 клик, то данные о таких заказах также должны попадать в общий XML-файл.

Как настроить запись значения из GET-параметра admitad_uid в cookies

Значение admitad_uid фиксируется при переходе пользователя на сайт. Вам нужно сохранить его в cookies на количество дней, которое прописано в договоре с Admitad (по умолчанию 90 дней).

Для этого с помощью скрипта настройте запись значения параметра admitad_uid в cookies.

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

Cookie или срок ее жизни не должны изменяться при переходе из бесплатных источников, таких как органический поиск и пр. Admitad работает по модели атрибуции Last Paid Click, при которой действие должно засчитываться последнему платному источнику трафика.

Ниже — примеры для JavaScript и PHP-скрипта. Вы можете использовать эти или любой другой язык программирования.

Обращайте внимание на комментарии в примерах кода. Комментарии добавлены после //.

if (isset($_GET['admitad_uid'])) {
$days = 90; // Количество дней хранения cookie
setcookie('_aid', $_GET['admitad_uid'], time() + 60 * 60 * 24 * $days, '/');
}

function get_admitad_uid() {
if (!isset($_COOKIE['_aid']) {
return null;
}

return $_COOKIE['_aid'];
}

<script type="text/javascript">
// Количество дней хранения cookie
var days_to_store = 90;

//Параметры создания cookie с UID admitad
var uid_cookie_name = 'admitad_uid'; // Название cookie, хранящая UID
var uid_channel_name = 'admitad_uid'; // Функция для получения источника из GET-параметра

function getParamFromUriAdmitad (get_param_name) {
   var pattern = get_param_name + '=([^&]+)';
   var re = new RegExp(pattern);
   return (re.exec(document.location.search) || [])[1] || '';
};

// функция для записи источника в cookie с именем cookie_name
function setAdmitadCookie (param_name, cookie_name) {
   var param = getParamFromUriAdmitad(param_name);
   if (!param) { return; }
   var period = days_to_store * 60 * 60 * 24 * 1000;   // в секундах
   var expiresDate = new Date((period) + +new Date);
   var cookieString = cookie_name + '=' + param + '; path=/; expires=' + expiresDate.toGMTString();
   document.cookie = cookieString;
   document.cookie = cookieString + '; domain=.' + location.host;
};

// запись cookie
setAdmitadCookie(uid_channel_name, uid_cookie_name);

</script>

Как настроить дедупликацию

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

Платный источник трафика — это любой сторонний ресурс, которому вы платите за привлечение пользователей на ваш сайт по определенным условиям: за каждый переход на сайт, просмотр рекламы, заявку, регистрацию или покупку.
Например, таргетированная и контекстная реклама, платные посты на каналах лидеров мнений и т.п.

Настройка дедупликации — обязательный этап для выполнения интеграции, даже если сейчас вы работаете только с одним платным источником трафика: партнерской сетью Admitad.

При настройке дедупликации, информация о действии передается в Admitad в соответствии с моделью атрибуции Last Paid Click: если последним платным источником был веб-мастер Admitad Partner Network, то действие должно быть засчитано Admitad.

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

Способ 1

1. Настройте создание cookie на всех страницах сайта, которая хранит последний платный источник трафика. По умолчанию Admitad передает параметр utm_source=admitad.

2. Настройте передачу информации о заказе в XML-файл для тех случаев, когда в cookie с источником трафика хранится значение параметра admitad.

Способ 2

Если был переход с GET-параметром источника трафика отличным от Admitad, настройте удаление cookie admitad_uid.

Как подготовить XML-файл для интеграции

Подготовьте XML-файл для интеграции. Для этого добавьте в него обязательные параметры. Также при необходимости вы можете добавить в файл дополнительные параметры.

В параметры должны подставляться данные о заказе, совершенном пользователем.
Важно! Логику подстановки этих параметров вам нужно реализовать самостоятельно.
Примеры XML-файлов

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

Типы действий:

Sale — пользователь купил товар или оформил / оплатил заказ.
Lead — пользователь заполнил форму и отправил свои данные: заявку на услугу, зарегистрировался и пр.

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

Чтобы проверить, какие действия есть в вашей партнерской программе, в личном кабинете перейдите в раздел «Действия» (Программа → Настройки трафика → Действия и вознаграждения).

Параметры для действия Sale

В столбце «Имя параметра» полужирным шрифтом выделены основные параметры, а курсивом выделены алиасы — дополнительные наименования для основного параметра.
Т.е. в настройках вы можете указать не основной параметр, а его алиас, и система Admitad также сможет его обработать.

Имя параметра	Описание	Тип	Примечание
uid, key	Идентификатор Admitad Partner Network	Строка	Генерируемое значение, которое передается в момент перехода пользователя на сайт в параметре `admitad_uid`. Если в своей программе вы разрешаете контекстную рекламу, то в случаях, когда пользователи переходят по контекстным объявлениям Google Ads веб-мастеров, в параметр `admitad_uid` вместо значения uid записывается значение gclid, которое генерирует Google. Чтобы трекинг действий работал корректно, ваш сервер должен принимать и передавать значение параметра gclid целиком. Подробнее о длине параметра gclid Пример:CjwKCAjwmJeYBhAwEiw AXlg0AfVR-r9TC-9ecMaEOJO7 rbkmyt6j9QNyDFKqZ9YQTF dWxO2lQxvhPBoCO1sQAvD_BwE
order_id, oid	Ваш внутренний идентификатор заказа	Строка, 1−100 символов	Ваш внутренний ID заказа. Важно! Убедитесь, что сможете найти в своей CRM-системе заказ по этому ID, так как по нему в дальнейшем будет проводиться сверка.
action_code, ac, product,product_code	Код целевого действия	Целое число	Переменная — сюда должен подставляться код соответствующего действия из настроек вашей программы. Как узнать код действия
tariff_code, tc	Код тарифа	Целое число	Переменная — сюда должен подставляться код соответствующего тарифа из настроек вашей программы. Как узнать код тарифа
currency_code	Код валюты	Строка, 3 символа	Определяется в ISO 4217. Подходят только буквенные значения. Пример: RUB, EUR, USD.
position_id	Номер позиции товара в корзине	Целое число	Переменная, значение которой изменяется от 1 до N, где N = position_count.
position_count	Количество позиций в корзине	Целое число	Переменная со значением N, которая зависит от состава корзины, оформленной пользователем.
quantity	Количество единиц товара в позиции	Целое число
payment_type	Тип целевого действия	Строка, 4 символа	Постоянная, значение — «sale».
product_id	Ваш внутренний идентификатор товара	Строка, 1−100 символов	ID товара, который должен соответствовать ID из товарного фида, если вы используете этот инструмент. Подробнее о товарном фиде
price	Стоимость одной позиции товара в корзине	Целое или дробное число	В качестве разделителя целой и дробной части обязательно нужно использовать точку. Пример: правильно — 2.65; неправильно — 2,65.
datetime_action, now	Дата и время совершения действия	Строка, 19 символов	Формат: ГГГГ-ММ-ДД чч:мм:сс. Пример: 2022-08-25 00:00:00

При желании вы можете добавить дополнительные параметры.

Имя параметра

Описание

Тип

Примечание

promocode

Код персонального промокода

Строка, 255 символов

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

Подробнее

tracking

Дополнительная информация по заказу

Строка, 255 символов

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

Параметры для действия Lead

В столбце «Имя параметра» полужирным шрифтом выделены основные параметры, а курсивом выделены алиасы — дополнительные наименования для основного параметра.
Т.е. в настройках вы можете указать не основной параметр, а его алиас, и система Admitad Partner Network также сможет его обработать.

Имя параметра	Описание	Тип	Примечание
uid, key	Идентификатор Admitad Partner Network	Строка	Генерируемое значение, которое передается в момент перехода пользователя на сайт в параметре `admitad_uid`. Если в своей программе вы разрешаете контекстную рекламу, то в случаях, когда пользователи переходят по контекстным объявлениям Google Ads веб-мастеров, в параметр `admitad_uid` вместо значения uid записывается значение gclid, которое генерирует Google. Чтобы трекинг действий работал корректно, ваш сервер должен принимать и передавать значение параметра gclid целиком. Подробнее о длине параметра gclid Пример: CjwKCAjwmJeYBhAwEiwAXlg0AfVR -r9TC-9ecMaEOJO7rbkmyt6 j9QNyDFKqZ9YQTFdWxO2l QxvhPBoCO1sQAvD_BwE
order_id, oid	Ваш внутренний идентификатор заказа	Строка, 1−100 символов	Ваш внутренний ID заказа. Важно! Убедитесь, что сможете найти в своей CRM-системе заказ по этому ID, так как по нему в дальнейшем будет проводиться сверка. Если для вашей партнерской программы нужно настроить несколько целевых действий, но при этом ID пользователя не изменяется, добавьте префикс в ID заказа. Подробнее
action_code, ac, product, product_code	Код целевого действия	Целое число	Переменная — сюда должен подставляться код соответствующего действия из настроек вашей программы. Как узнать код действия
tariff_code, tc	Код тарифа	Целое число	Переменная — сюда должен подставляться код соответствующего тарифа из настроек вашей программы. Как узнать код тарифа
datetime_action, now	Дата и время совершения действия	Строка, 19 символов	Формат: ГГГГ-ММ-ДД чч:мм:сс. Пример: 2022-08-25 00:00:00

При желании вы можете добавить дополнительные параметры.

Имя параметра	Описание	Тип	Примечание
currency_code	Код валюты	Строка, 3 символа	Определяется в ISO 4217. Подходят только буквенные значения. Пример: RUB, EUR, USD.
position_id	Номер позиции товара в корзине	Целое число	Переменная, значение которой изменяется от 1 до N, где N = position_count.
position_count	Количество позиций в корзине	Целое число	Переменная со значением N, которая зависит от состава корзины, оформленной пользователем.
quantity	Количество единиц товара в позиции	Целое число
payment_type	Тип целевого действия	Строка, 4 символа	Постоянная, значение — «lead».
product_id	Ваш внутренний идентификатор товара	Строка, 1−100 символов	ID товара, который должен соответствовать ID из товарного фида, если вы используете этот инструмент. Подробнее о товарном фиде
price	Стоимость одной позиции товара в корзине	Целое или дробное число	В качестве разделителя целой и дробной части обязательно нужно использовать точку. Пример: правильно — 2.65; неправильно — 2,65.
promocode	Код персонального промокода	Строка, 255 символов	Используйте этот параметр, если вам требуется настроить передачу персональных промокодов. Подробнее
tracking	Дополнительная информация по заказу	Строка, 255 символов	Используйте этот параметр, чтобы передать дополнительную информацию для специалистов Admitad на этапе сверки.

Примеры XML-файлов

В этом разделе представлены примеры XML-файлов в зависимости от типа целевого действия пользователя.

Чтобы ознакомиться с нужным примером, нажмите на него.

Ниже представлен пример корзины с тремя товарами.

Товарная позиция	Наименование товара	Цена	Количество товара	Сумма товарной позиции
1	Бензопила	2000	3	6000
2	Настольная лампа	1790	2	3580
3	Сварочный аппарат	4050	1	4050
			Итого	13 630

Каждую позицию товара необходимо вынести в отдельный тег <payment>.
В примере ниже внутри тегов <payment> изменяются значения следующих параметров:

количество (quantity);
цена (price);
порядковый номер товарной позиции в корзине (position_id);
код целевого действия (action_code);
код тарифа (tariff_code);
внутренний идентификатор товара (product_id).

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>125</product_id>
        <tracking>Ручные инструменты - бензопила</tracking>
        <quantity>3</quantity>
        <currency_code>RUB</currency_code>
        <price>2000</price>
        <position_id>1</position_id>
        <payment_type>sale</payment_type>
        <action_code>1</action_code>
        <tariff_code>1</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>57</product_id>
        <tracking>Настольная лампа</tracking>
        <quantity>2</quantity>
        <currency_code>RUB</currency_code>
        <price>1790</price>
        <position_id>2</position_id>
        <payment_type>sale</payment_type>
        <action_code>2</action_code>
        <tariff_code>2</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>71</product_id>
        <tracking>Сварочный аппарат</tracking>
        <quantity>1</quantity>
        <currency_code>RUB</currency_code>
        <price>4050</price>
        <position_id>3</position_id>
        <payment_type>sale</payment_type>
        <action_code>2</action_code>
        <tariff_code>1</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
</payment_list>

Ниже представлен пример целевого действия для банковской сферы (тип действия — lead).

Товарная позиция	Наименование товара	Цена	Количество товара	Сумма товарной позиции
1	Регистрация	-	-	-

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <payment_type>lead</payment_type>
        <action_code>1</action_code>
        <tariff_code>1</tariff_code>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
</payment_list>

Как настроить отправку информации по персональным промокодам

Персональные промокоды — это промокоды, которые содержат уникальное кодовое слово, по которому отслеживаются целевые действия. Такие промокоды закрепляются за конкретными веб-мастерами. Подробнее о персональных промокодах

Если вы планируете работать с персональными промокодами:

1. Убедитесь, что в форме оформления заказа на сайте присутствует поле «Промокод».

2. Запишите уникальный промокод из формы оформления заказа в параметр promocode.

3. Убедитесь, что все заказы с уникальным промокодом отправляются в Admitad Partner Network. Для этого протестируйте запрос.

Вам нужно передать в Admitad информацию о заказе в случаях, если в запросе есть:

и admitad_uid, и персональный промокод;
только персональный промокод;
только admitad_uid.

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

Как тестировать XML-файл после настройки

1. После того как вы создадите XML-файл описанной выше структурой и настроите отправку в него данных о совершенных действиях пользователей, получите ссылку для тестирования в разделе «Интеграция».

1.1 В личном кабинете перейдите в раздел «Интеграция» (Программа → Интеграция).

1.2 Затем нажмите «Далее» и на странице «Способы интеграции» переключитесь на вкладку «Кастомная интеграция».

1.3 На вкладке «Кастомная интеграция» выберите «XML» и нажмите «Далее».

1.4 Промотайте страницу вниз до блока «Тестирование интеграции» и скопируйте тестовую ссылку из соответствующего поля.

2. Сделайте тестовые заказы и убедитесь, что:

Значение параметра admitad_uid обрабатывается на всех страницах сайта и сохраняется в cookie.
Срок жизни cookie с admitad_uid соответствует сроку, указанному в договоре или, если договора нет, то сроку в 90 дней.
Cookie не удаляется при переходе пользователя через органический поиск.
Чтобы это проверить, при совершении тестового заказа:
- 1. Сначала перейдите по тестовой партнерской ссылке.
- 2. Затем перейдите по органической ссылке.
- 3. Сделайте заказ и проверьте, что он отобразится в системе.
Отправка данных в XML-файл работает для всех целевых действий и тарифов вашей партнерской программы.
Для этого сделайте несколько заказов, чтобы проверить, что в каждом случае трекинг работает корректно.
Для каждой товарной позиции в корзине создается свой тег <payment>.
Номер и сумма заказа передаются корректно — стоимость каждого товара должна передаваться за вычетом промокодов и доставки, т.е. именно та сумма, которую пользователь заплатил за товар.

3. Затем проверьте другие настройки, если используете их.

Если вы используете персональные промокоды, сделайте тестовый заказ по следующей схеме:
- 1. Перейдите на свой сайт по прямой ссылке без параметров.
- 2. Используйте персональный промокод при оформлении заказа и убедитесь, что заказ засчитан Admitad Partner Network.
Если вы используете другие платные источники, сделайте тестовый заказ по следующей схеме:
- 1. Перейдите по партнерской ссылке из другого источника.
- 2. Перейдите по партнерской ссылке Admitad.
- 3. Сделайте заказ и убедитесь, что он был засчитан Admitad.
Если у вас есть:
- мобильная версия сайта,
- форма быстрого заказа
- и/или форма заказа в 1 клик,
проверьте, что трекинг настроен для всех платформ и способов покупки.

4. После того как вы сделаете тестовые заказы, вам нужно сообщить специалистам Admitad о том, как получить доступ к XML-файлу с информацией по этим заказам. Специалисты выгрузят и обработают файл в течение 3−4 дней.

5. Если трекинг настроен корректно, в течение часа действия появятся в статистике Admitad.

Чтобы проверить это, перейдите в свой личный кабинет Admitad → «Статистика» → «По действиям» и убедитесь, что в статистике корректно отображается целевое действие и данные по нему:

название целевого действия в колонке «Тариф» в статистике соответствует названию этого действия в разделе «Действия»;
ID действия в колонке «ID заказа» соответствует ID действия в вашей системе;
сумма заказа в Admitad соответствует сумме тестового заказа.

Сообщите техническому специалисту Admitad, что тестирование прошло успешно. После этого программа будет поставлена на подготовку к запуску.

6. Если действие не появилось в статистике в течение часа, убедитесь, что:

отправили техническому специалисту Admitad правильную ссылку на файл;
корректно указали все обязательные параметры;
использовали в тегах верный регистр.

Чтобы выявить ошибку, перейдите в раздел «Журнал запросов» (Программа → Интеграция → Тестирование интеграции). Текст ошибки будет указан в поле «Результат».

Исправьте ошибку и проведите повторный тест. Подробнее о разделе «Журнал запросов»

FAQ

Где найти значение параметра action_code?

1. В личном кабинете перейдите в раздел «Интеграция» (Программа → Интеграция).

2. Затем нажмите «Далее» и на странице «Способы интеграции» переключитесь на вкладку «Кастомная интеграция».

3. На вкладке «Кастомная интеграция» выберите «XML» и нажмите «Далее».

4. В таблице в столбце «Действие» найдите то, код которого вам нужен.
Значение параметра action_code представлено в строке с этим действием в столбце «Код действия» (блок «Настройка интеграции: уникальные значения параметров для вашей программы»).

Где найти значение параметра tariff_code?

1. В личном кабинете перейдите в раздел «Интеграция» (Программа → Интеграция).

2. Затем нажмите «Далее» и на странице «Способы интеграции» переключитесь на вкладку «Кастомная интеграция».

3. На вкладке «Кастомная интеграция» выберите «XML» и нажмите «Далее».

4. Во второй таблице на странице в столбце «Тариф» найдите тот, код которого вам нужен.

Значение параметра tariff_code представлено в строке с этим тарифом в столбце «Код тарифа» (блок «Настройка интеграции: уникальные значения параметров для вашей программы»).

Как записать параметр order_id для нескольких действий, если в качестве номера заказа выступает ID пользователя ?

В некоторых партнерских программах, например, в программах категории «Онлайн-игры», в статистике часто используется не номер заказа, а ID пользователя в системе.

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

Целевое действие	Параметр и его значение	Использованный префикс
Регистрация	order_id=reg_123123	reg_
Получение 5 уровня	order_id=lvl5_123123	lvl5_

Вернуться к обязательным параметрам