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

  • Обновлено

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

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

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

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

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

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

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 Affiliate работает по модели атрибуции Last Paid Click, согласно которой действие должно засчитываться последнему платному источнику трафика.

 

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

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

 

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

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-файла

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

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

Описание Тип Примечание
 uid идентификатор Admitad Affiliate   строка значение генерируемое, приходит на входе пользователя на сайт в параметре admitad_uid


Если вы разрешаете контекстную рекламу в своей программе, то в случаях, когда пользователи переходят по контекстным объявлениям Google Ads веб-мастеров, в параметр admitad_uid вместо значения uid записывается значение gclid, которое генерирует Google.


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

order_id ваш внутренний id заказа строка, 1-100
символов

ваш внутренний id заказа

Важно! Убедитесь, что сможете найти в своей CRM заказ по этому id, так как по нему в дальнейшем будет проводиться сверка.

action_code код целевого действия целое число переменная, значение сообщает специалист отдела трекинга в начале интеграции
tariff_code код тарифа целое число переменная, значение сообщает специалист отдела трекинга в начале интеграции
currency_code код валюты строка, 3 символа определяется в ISO 4217; принимаются только буквенные значения
position_id  номер позиции товара в корзине целое число переменная, значение изменяется от 1 до N, где N = position_count
position_count количество позиций в корзине целое число переменная, значение N, зависит от состава корзины, оформленной пользователем
quantity количество единиц товара в позиции целое или дробное неотрицательное
число
 
payment_type тип целевого действия строка, 4 символа константа, значение sale/lead
product_id ваш внутренний id товара строка, 1-100 символов ваш внутренний id товара, должен соответствовать ID из товарного фида.
price стоимость одной позиции товара в корзине целое или дробное неотрицательное число

 

datetime_action дата и время совершения действия строка, 19 символов формат ГГГГ-ММ-ДД чч:мм:сс

 

По желанию можно добавить параметр 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.

 Имя параметра  Описание  Тип
 promocode  код уникального промокода  строка, 255 символов


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

  • присутствует и 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 Affiliate и запросите партнерскую ссылку для тестирования.

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

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

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

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

 

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

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

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

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

Была ли эта статья полезной?