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

 

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

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

 

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

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

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

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 правильную ссылку на файл;
  • структура файла соответствует заданной;
  • использован верный регистр в тегах.

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

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