Интеграция через XML

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

Особенности интеграции через XML:

• Можно ограничить доступ к файлу при помощи логина и пароля.
• При соответствующих настройках веб-мастера могут получать информацию о действиях с минимальной задержкой.
• В случае технических неполадок легко восстановить действия в статистике Admitad Partner Network.
• В случае увеличения очереди обработки возможны задержки в появлении данных.
• При наличии мобильной версии сайта или мобильного приложения, форм быстрого заказа или заказа в 1 клик их также необходимо проинтегрировать.
• В XML-файл должны отправляться данные только о действиях пользователей, пришедших от Admitad Partner Network. Для идентификации таких пользователей служит параметр admitad_uid.
   

Что такое admitad_uid. Механизм работы партнерской ссылки

В ходе работы с партнерской программой веб-мастер размещает на своей площадке ее партнерскую ссылку. Партнерская ссылка генерируется на основании ссылки для перехода — ссылки, ведущей на сайт программы и содержащей необходимые Admitad Partner Network GET-параметры и специальные utm-метки. Один из GET-параметров обязательно должен передавать значение admitad_uid — уникального идентификатора, который генерируется на стороне Admitad Partner Network в момент перехода пользователя по ссылке. В admitad_uid хранится служебная информация о веб-мастере и источнике перехода, на основании которой система Admitad Partner Network распознает, кто из веб-мастеров привел пользователя на сайт и кому должны быть засчитаны его действия.

Пример ссылки для перехода:

https://site.ru/?admitad _uid={{admitad_uid}}

Значение параметра admitad_uid необходимо получить из GET-параметра на входе пользователя на сайт и сохранить его на 90 дней в cookies. После авторизации пользователя при наличии cookie необходимо записать admitad_uid в БД и связать с личным кабинетом пользователя. Пользователь может перейти по ссылке на любую страницу сайта, поэтому admitad_uid необходимо отслеживать на всех страницах. При совершении действия пользователем нужно проверить, есть ли у него admitad_uid. Если admitad_uid есть, значение необходимо передать в XML-файл.

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

Общая схема работы

Краткие шаги интеграции

1. Реализация алгоритма создания cookie и записи значения admitad_uid в нее.

2. Реализация алгоритма чтения admitad_uid из cookie и записи в БД при авторизации пользователя.

3. Определение цены, количества и прочих параметров для каждого товара в корзине.

4. Экспорт данных в XML-файл.

Запись GET-параметра admitad_uid в cookies с помощью PHP

if (isset($_GET['admitad_uid'])) {
$days = 90;
setcookie('_aid', $_GET['admitad_uid'], time() + 60 * 60 * 24 * $days, '/');
}

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

return $_COOKIE['_aid'];
} 

Структура XML-файла

Обязательные параметры

По желанию можно добавить параметр client_id — ваш внутренний id клиента.

Пример 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>1</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>1</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
     </payment>
</payment_list>

Пример 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>1</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>

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

Настройка передачи уникальных промокодов

Уникальные промокоды — промокоды, закрепленные за конкретным веб-мастером. Подробнее о них здесь.

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

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

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

3. При наличии уникального промокода заказ должен быть включен в XML-выгрузку независимо от наличия admitad_uid.
    В Admitad Partner Network заказ должен передаваться в следующих случаях:

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

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

Пример 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>1</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>1</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
        <promocode>10OFF</promocode>
    </payment>
</payment_list>

Порядок тестирования

1. После того как вы создадите XML-файл с заданной структурой и настроите отправку в него данных о совершенных действиях, свяжитесь с отделом трекинга Admitad Partner Network и запросите партнерскую ссылку для тестирования.

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

• admitad_uid обрабатывается на всех страницах сайта;
• admitad_uid сохраняется в cookie и в БД, и привязывается к личному кабинету пользователя;
• срок жизни куки с admitad_uid соответствует договору, cookie не удаляется при переходе пользователя через органический поиск;
• отправка данных в XML-файл работает для всех целевых действий и тарифов вашей партнерской программы;
• для каждой товарной позиции в корзине создается свой тег <payment>;
• номер и сумма заказа передаются корректно;
• трекинг настроен на мобильной версии сайта (если есть), формах быстрого заказа и заказа в 1 клик и пр.

3. Если трекинг настроен корректно, действия появятся в статистике Admitad Partner Network (Личный кабинет → Статистика → По действиям).

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

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

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

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