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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ниже — примеры для 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.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();
    = cookieString;
    = cookieString + '; domain=.' + location.host;
};

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

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

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

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

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

Способ 1

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

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

Способ 2

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

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

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

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

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

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

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

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

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

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

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

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

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

<?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>

<?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-файл описанной выше структурой и настроите отправку в него данных о совершенных действиях пользователей, получите ссылку для тестирования в разделе «Интеграция».

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). При этом нужно использовать префиксы, из названия которых будет понятно, какое целевое действие вы имеете в виду.