Інтеграція через XML-файл

Інтеграція — це процес, під час якого ви налаштовуєте передачу інформації про цільові дії, що виконуються на вашому сайті, до системи Admitad.

Цільова дія — це купівля, реєстрація, заповнення заявки або інша очікувана дія, яку виконав користувач, приведений на ваш сайт вебмайстером Admitad.

Загальна інформація: особливості та рекомендації

Ви можете розпочати інтеграцію лише за умови, що для вашої програми виконано таке:
- Посилання для трекінгу вже згенеровано у General Settings.
- Додано цільову дію та налаштовано відповідну ставку в розділі Actions.

Якщо у вас немає менеджера, потрібно самостійно згенерувати посилання для трекінгу (див. цю інструкцію), а також додати принаймні одну дію і одну ставку (див. цю інструкцію).
Якщо у вас є персональний менеджер, він зробить це за вас.

Інтеграція — обов’язковий крок для продовження роботи та запуску партнерської програми з Admitad.
Щоб пришвидшити інтеграцію, ви можете залучити свого спеціаліста й делегувати цей процес йому, надавши цю інструкцію.

Після завершення інтеграції всі дані про цільові дії (дата, номер замовлення, сума замовлення тощо) будуть автоматично передаватися у Admitad.

Що таке інтеграція через XML-файл і як вона працює

Інтеграція через XML-файл — це спосіб підключення вашого сайту до системи Admitad, коли на вашому сервері необхідно створити XML-файл певної структури, у якому зберігатиметься інформація про цільові дії на вашому сайті.

Як це працює. Використовуючи постійне посилання на ваш XML-файл, що зберігається на вашому сервері, сервер Admitad Partner Network у визначені регулярні інтервали звертатиметься до цього файлу та завантажуватиме нові дані про цільові дії у звіти Admitad.

Щоб переконатися, що доступ до XML-файлу має лише Admitad Partner Network, ви можете обмежити доступ до файлу. Наприклад, ви можете налаштувати доступ із логіном та паролем або зазначити IP-адресу сервера Admitad.

Рекомендується встановити якомога вищу частоту оновлення даних у вашому XML-файлі, щоб:

Інформація у звітах Admitad регулярно й оперативно оновлюється
Вебмайстери можуть відстежувати свої результати в режимі реального часу

Детальніше про інші способи інтеграції читайте у статті Вибір способу інтеграції.

Як інтегрувати вашу систему через XML-файл

Щоб інтегрувати ваш сайт через XML-файл, виконайте такі дії (інструкції до кожного кроку наведені нижче):

Налаштуйте збереження значення параметра admitad_uid у cookie-файл.
Налаштуйте дедуплікацію цільових дій.
Підготуйте ваш XML-файл
Протестуйте інтеграцію.

Якщо у вашого сайту є як веб-, так і мобільна версія та/або швидка форма замовлення чи форма замовлення в один клік, переконайтеся, що інформація про замовлення, зроблені у цих розділах, також передається у ваш XML-файл.

Як налаштувати збереження значення з GET-параметра admitad_uid у cookie

Значення admitad_uid реєструється під час відвідування користувачем вашого сайту. Збережіть це значення у cookie-файлі й тримайте його там протягом кількості днів, визначеної вашою угодою з Admitad (за замовчуванням 90 днів).

Використайте скрипт для налаштування збереження admitad_uid у cookie-файл.

Додайте код відстеження значення 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, що містить значення Admitad UID
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).

Після налаштування дедуплікації дані про цільові дії передаються в Admitad за моделлю атрибуції Last Paid Click. Якщо вебмайстер Admitad був останнім платним джерелом трафіку, ця дія повинна бути віднесена до 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 ID	Рядок	Згенероване значення, яке передається у `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-системі. Цей ідентифікатор використовується під час верифікації.
action_code, ac, product,product_code	Код цільової дії	Ціле число	Змінна — код цільової дії з налаштувань вашої програми. Як знайти код дії
tariff_code, tc	Код тарифу	Ціле число	Змінна — код тарифу з налаштувань вашої програми. Як знайти код тарифу
currency_code	Код валюти	Рядок, 3 символи	Визначається відповідно до ISO 4217. Тільки літери. Приклад: EUR, USD.
position_id	Номер товару у кошику	Ціле число	Змінна від 1 до N, де N = position_count.
position_count	Кількість товарів у кошику	Ціле число	Змінна зі значенням N, що залежить від умісту кошика користувача.
quantity	Кількість товару	Ціле число
payment_type	Тип цільової дії	Рядок, 4 символи	Константа зі значенням «sale».
product_id	Ваш внутрішній ID товару	Рядок, від 1 до 100 символів	ID товару, який має відповідати ID з товарного фіда, якщо ви використовуєте цей інструмент. Дізнатися більше про товарний фід
price	Вартість товару	Ціле або десяткове число	Використовуйте крапку як роздільник. Приклад: Коректно: 2.65 Некоректно: 2,65
datetime_action, now	Дата й час дії	Рядок, 19 символів	Формат: YYYY-MM-DD hh:mm:ss. Приклад: 2022-08-25 00:00:00

Можна додати додаткові параметри, якщо потрібно.

Назва параметра

Опис

Тип

Примітка

promocode

Персональний промокод

Рядок, 255 символів

Використовуйте цей параметр, якщо потрібно передавати персональні промокоди.

Дізнатися більше

tracking

Додаткова інформація про замовлення

Рядок, 255 символів

Використовуйте цей параметр для передачі додаткової інформації для спеціалістів Admitad під час верифікації.

Параметри для Lead

Назва параметра	Опис	Тип	Примітка
uid, key	Admitad ID	Рядок	Згенероване значення, яке передається у `admitad_uid` під час відвідування сайту користувачем. Якщо ви дозволяєте контекстну рекламу, у момент кліку користувача за контекстною рекламою від вебмайстрів через Google Ads у `admitad_uid` буде записано значення gclid, згенероване Google, замість uid. Щоб відстеження дій працювало коректно, ваш сервер має приймати та передавати значення gclid повністю. Приклад: CjwKCAjwmJeYBhAwEiwAXlg0AfVR -r9TC-9ecMaEOJO7rbkmyt6 j9QNyDFKqZ9YQTFdWxO2l QxvhPBoCO1sQAvD_BwE
order_id, oid	Ваш внутрішній ідентифікатор замовлення	Рядок, від 1 до 100 символів	Ваш внутрішній ідентифікатор замовлення. Примітка: Переконайтесь, що ви можете знайти замовлення за цим ID у вашій CRM-системі. Цей ідентифікатор використовується під час верифікації. Якщо для вашої партнерської програми потрібно налаштувати кілька цільових дій, але id користувача залишиться тим самим, додайте префікс до order ID. Дізнатися більше
action_code, ac, product, product_code	Код цільової дії	Ціле число	Змінна — код цільової дії з налаштувань вашої програми. Як знайти код дії
tariff_code, tc	Код тарифу	Ціле число	Змінна — код тарифу з налаштувань вашої програми. Як знайти код тарифу
datetime_action, now	Дата й час дії	Рядок, 19 символів	Формат: YYYY-MM-DD hh:mm:ss. Приклад: 2022-08-25 00:00:00

Можна додати додаткові параметри, якщо потрібно.

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

Приклади XML-файлів

У цьому розділі наведено приклади XML-файлів для різних типів цільових дій.

Натисніть на приклад, щоб дізнатися більше.

Нижче наведено приклад кошика з трьома товарами.

Товар	Назва товару	Вартість	Кількість	Сума
1	Бензопила	2,000	3	6,000
2	Настільна лампа	1,790	2	3,580
3	Зварювальний апарат	4 050	1	4 050
			Разом	13 630

Призначте унікальний тег <payment> для кожного товару.
У наведеному нижче прикладі всередині тегів змінюються значення таких параметрів:

кількість ( quantity
)
ціна ( price
)
номер товару в кошику ( position_id
)
код цільової дії ( action_code
);
код ставки ( tariff_code
)
внутрішній ID товару ( 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>Handheld tools - Chainsaw</tracking>
        <quantity>3</quantity>
        <currency_code>USD</currency_code>
        <price>2,000</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>Desk lamp</tracking>
        <quantity>2</quantity>
        <currency_code>USD</currency_code>
        <price>1,790</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>Welding set</tracking>
        <quantity>1</quantity>
        <currency_code>USD</currency_code>
        <price>4,050</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. Переконайтеся, що у формі замовлення на вашому сайті є поле Promo code.

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

3. Переконайтеся, що всі замовлення з унікальним промокодом передаються в Admitad. Протестуйте запит, щоб бути впевненими на 100%.

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

І admitad_uid
та персональний промокод
Лише персональний промокод
admitad_uid
лише

Інформацію про замовлення з персональним промокодом не можна надсилати в інші канали.

Як протестувати XML-файл після налаштування

1. Після створення XML-файлу зі структурою, описаною вище, і налаштування передачі даних про цільові дії, ви отримаєте тестове посилання в розділі Integration.

1.1 У вашому акаунті перейдіть до розділу Integration (Program → Integration).
1.2 Натисніть Next і на сторінці Integration methods відкрийте вкладку Custom integration).
1.3 У Custom integration виберіть XML і натисніть Next.
1.4 Прокрутіть сторінку до розділу Integration testing і скопіюйте тестове посилання з відповідного поля.

2. Розмістіть кілька тестових замовлень і переконайтеся, що:

Значення admitad_uid
обробляється на всіх сторінках сайту й записується у cookie.
Термін дії cookie зі значенням admitad_uid
відповідає зазначеному в договорі. Якщо договір не укладено, він має становити 90 днів.
Cookie не видаляється, якщо користувач перейшов з органічного пошуку.
Щоб це перевірити, під час тестового замовлення виконайте наступне:
- 1. Перейдіть за тестовим партнерським посиланням.
- 2. Перейдіть за органічним посиланням.
- 3. Оформіть замовлення й перевірте, чи з'явилося воно в системі.
Запис даних у XML-файл працює для всіх цільових дій і ставок, які використовуються у вашій програмі.
Перевірте це, оформивши кілька замовлень і переконавшись у безперервності трекінгу в кожному випадку.
Для кожного товару в кошику створюється унікальний тег <payment>.
Номер замовлення і сума передаються правильно. Щодо вартості кожного товару: необхідно передати саме суму, яку користувач реально сплатив після застосування промокоду, без вартості доставки.

2. Перевірте інші параметри, якщо використовуєте їх.

Якщо використовуєте персональні промокоди, оформіть тестове замовлення так:
- 1. Перейдіть на свій сайт за прямим посиланням без параметрів.
- 2. Використайте персональний промокод у вашому замовленні й переконайтеся, що Admitad зарахував замовлення.
Якщо ви використовуєте інші платні джерела, оформіть тестове замовлення так:
- 1. Перейдіть за партнерським посиланням з іншого джерела.
- 2. Перейдіть з партнерської мережі Admitad.
- 3. Оформіть замовлення й переконайтеся, що Admitad зарахував його.
Якщо у вас є:
- мобільна версія сайту
- швидка форма замовлення
- та/або форма замовлення в один клік,
переконайтеся, що трекінг налаштований для всіх платформ і способів покупки.

4. Після оформлення тестових замовлень дайте інструкцію фахівцям Admitad, як отримати доступ до вашого XML-файлу з інформацією про замовлення. Фахівці завантажать і оброблять файл протягом 3–4 днів.

5. Якщо трекінг працює коректно, дії з'являться у звітах Admitad протягом години.

Щоб це перевірити, перейдіть у Admitad account → Reports → On actions і переконайтеся, що у звіті коректно відображається цільова дія та її інформація:

Назва цільової дії у стовпці Rate звіту співпадає з назвою цієї дії в розділі Actions.
ID дії у стовпці Order ID відповідає ID дії у вашій системі.
Сума замовлення в Admitad відповідає сумі тестового замовлення.

Повідомте фахівцю Admitad про успішний тест. Програму буде підготовлено до запуску.

6. Якщо дія не з'явилася у звітах за годину, перевірте, що:

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

Щоб знайти помилку, перейдіть у розділ Request log (Program → Integration → Integration test). Текст помилки буде відображено у Result.

Виправте помилку й запустіть ще один тест. Дізнайтеся більше про Request log

FAQ

Де знайти значення action_code?

1. У вашому акаунті перейдіть до розділу Integration (Program → Integration).

2. Натисніть Next і на сторінці Integration methods відкрийте вкладку Custom integration).

3. У Custom integration виберіть XML і натисніть Next.

4. У стовпці Action таблиці знайдіть дію, код якої вам потрібен.
Значення action_code знаходиться у цій дії у стовпці Action code (Integration setup: унікальні значення параметрів для вашої програми).

Де знайти значення tariff_code?

1. У вашому акаунті перейдіть до розділу Integration (Program → Integration).

2. Натисніть Next і на сторінці Integration methods відкрийте вкладку Custom integration).

3. У Custom integration виберіть XML і натисніть Next.

4. У стовпці Rate другої таблиці знайдіть ставку, код якої вам потрібен.

Знайдіть tariff_code значення цієї ставки у стовпці Rate code (Integration setup: унікальні значення параметрів для вашої програми).

Як записувати order_id для кількох дій, якщо номер замовлення — це ID користувача?

Деякі партнерські програми (наприклад, онлайн-ігри) використовують ID користувача замість номера замовлення у звітах.

Тому, якщо потрібно додати кілька цільових дій для таких програм, до order ID (order_id) необхідно додати префікс. Використовуйте префікси, які чітко позначають відповідну дію.

Цільова дія	Параметр і його значення	Префікс
Реєстрація	order_id=reg_123123	reg_
Досягнення рівня 5	order_id=lvl5_123123	lvl5_

Повернутися до обов'язкових параметрів