1. Admitad
  2. Admitad Advertisers
  3. Техническая интеграция

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

  • Обновлено

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

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

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

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

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

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

  • Чтобы ускорить интеграцию, рекомендуем привлечь к ее выполнению вашего собственного технического специалиста и передать ему эту инструкцию.

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

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

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

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

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

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

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

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

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

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

Если кроме веб-версии сайта у вас есть мобильная версия сайта и/или форма быстрого заказа или заказа в 1 клик, то данные о таких заказах также должны попадать в общий XML-файл.

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

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

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

Чтобы сделать это, добавьте код для отслеживания значения параметра 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 с 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(document.location.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();
       document.cookie = cookieString;
       document.cookie = cookieString + '; domain=.' + location.host;
    };

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

    </script>

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

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

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

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

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

    Имя параметра Описание Тип Примечание
    uid, key Идентификатор Admitad Partner Network Строка

    Генерируемое значение, которое передается в момент перехода пользователя на сайт в параметре 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-системе заказ по этому ID, так как по нему в дальнейшем будет проводиться сверка.
    action_code, ac, product,product_code Код целевого действия Целое число

    Переменная — сюда должен подставляться код соответствующего действия из настроек вашей программы.

    Как узнать код действия
    tariff_code, tc Код тарифа Целое число

    Переменная — сюда должен подставляться код соответствующего тарифа из настроек вашей программы.

    Как узнать код тарифа
    currency_code Код валюты Строка, 3 символа

    Определяется в ISO 4217. Подходят только буквенные значения.

    Пример: RUB, EUR, USD.
    position_id Номер позиции товара в корзине Целое число Переменная, значение которой изменяется от 1 до N, где N = position_count.
    position_count Количество позиций в корзине Целое число Переменная со значением N, которая зависит от состава корзины, оформленной пользователем.
    quantity Количество единиц товара в позиции Целое число  
    payment_type Тип целевого действия Строка, 4 символа Постоянная, значение — «sale».
    product_id Ваш внутренний идентификатор товара Строка, 1−100 символов

    ID товара, который должен соответствовать ID из товарного фида, если вы используете этот инструмент.

    Подробнее о товарном фиде
    price Стоимость одной позиции товара в корзине Целое или дробное число

    В качестве разделителя целой и дробной части обязательно нужно использовать точку.

    Пример:

    • правильно — 2.65;
    • неправильно — 2,65.
    datetime_action, now Дата и время совершения действия Строка, 19 символов

    Формат: ГГГГ-ММ-ДД чч:мм:сс.

    Пример: 2022-08-25 00:00:00

  • При желании вы можете добавить дополнительные параметры.

    Имя параметра Описание Тип Примечание
    promocode Код промокода Take&Go Строка, 255 символов

    Используйте этот параметр, если вам требуется настроить передачу промокодов Take&Go.

    Подробнее
    tracking Дополнительная информация по заказу Строка, 255 символов Используйте этот параметр, чтобы передать дополнительную информацию для специалистов Admitad Partner Network на этапе сверки.

 

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

  • В столбце «Имя параметра» полужирным шрифтом выделены основные параметры, а курсивом выделены алиасы — дополнительные наименования для основного параметра.
    Т.е. в настройках вы можете указать не основной параметр, а его алиас, и система Admitad Partner Network также сможет его обработать.

    Имя параметра Описание Тип Примечание
    uid, key Идентификатор Admitad Partner Network Строка

    Генерируемое значение, которое передается в момент перехода пользователя на сайт в параметре admitad_uid.

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

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

    Пример: CjwKCAjwmJeYBhAwEiwAXlg0AfVR
    -r9TC-9ecMaEOJO7rbkmyt6
    j9QNyDFKqZ9YQTFdWxO2l
    QxvhPBoCO1sQAvD_BwE
    order_id, oid Ваш внутренний идентификатор заказа Строка, 1−100 символов

    Ваш внутренний ID заказа.

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

    Если для вашей партнерской программы нужно настроить несколько целевых действий, но при этом ID пользователя не изменяется, добавьте префикс в ID заказа. Подробнее
    action_code, ac, product, product_code Код целевого действия Целое число

    Переменная — сюда должен подставляться код соответствующего действия из настроек вашей программы.

    Как узнать код действия
    tariff_code, tc Код тарифа Целое число

    Переменная — сюда должен подставляться код соответствующего тарифа из настроек вашей программы.

    Как узнать код тарифа
    datetime_action, now Дата и время совершения действия Строка, 19 символов

    Формат: ГГГГ-ММ-ДД чч:мм:сс.

    Пример: 2022-08-25 00:00:00

  • При желании вы можете добавить дополнительные параметры.

    Имя параметра Описание Тип Примечание
    currency_code Код валюты Строка, 3 символа

    Определяется в ISO 4217. Подходят только буквенные значения.

    Пример: RUB, EUR, USD.
    position_id Номер позиции товара в корзине Целое число Переменная, значение которой изменяется от 1 до N, где N = position_count.
    position_count Количество позиций в корзине Целое число Переменная со значением N, которая зависит от состава корзины, оформленной пользователем.
    quantity Количество единиц товара в позиции Целое число  
    payment_type Тип целевого действия Строка, 4 символа Постоянная, значение — «lead».
    product_id Ваш внутренний идентификатор товара Строка, 1−100 символов

    ID товара, который должен соответствовать ID из товарного фида, если вы используете этот инструмент.

    Подробнее о товарном фиде
    price Стоимость одной позиции товара в корзине Целое или дробное число

    В качестве разделителя целой и дробной части обязательно нужно использовать точку.

    Пример:

    • правильно — 2.65;
    • неправильно — 2,65.
    promocode Код промокода Take&Go Строка, 255 символов

    Используйте этот параметр, если вам требуется настроить передачу промокодов Take&Go.

    Подробнее
    tracking Дополнительная информация по заказу Строка, 255 символов Используйте этот параметр, чтобы передать дополнительную информацию для специалистов Admitad Partner Network на этапе сверки.

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

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

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

  • Ниже представлен пример корзины с тремя товарами.

    Товарная позиция Наименование товара Цена Количество товара Сумма товарной позиции
    1 Бензопила 2000 3 6000
    2 Настольная лампа 1790 2 3580
    3 Сварочный аппарат 4050 1 4050
          Итого 13 630

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

    • количество (quantity);
    • цена (price);
    • порядковый номер товарной позиции в корзине (position_id);
    • код целевого действия (action_code);
    • код тарифа (tariff_code);
    • внутренний идентификатор товара (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>Ручные инструменты - бензопила</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>

  • Ниже представлен пример целевого действия для банковской сферы (тип действия — 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>

Как настроить отправку информации по промокодам Take&Go

Промокоды Take&Go — это промокоды, которые содержат уникальное кодовое слово, по которому отслеживаются целевые действия. Такие промокоды закрепляются за конкретными веб-мастерами. Подробнее о промокодах Take&Go

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

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

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

3. Убедитесь, что все заказы с уникальным промокодом отправляются в Admitad Partner Network. Для этого протестируйте запрос.

Вам нужно передать в Admitad Partner Network информацию о заказе в случаях, если в запросе есть:

  • и admitad_uid, и промокод Take&Go;
  • только промокод Take&Go;
  • только admitad_uid.

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

Как тестировать XML-файл после настройки

1. После того как вы создадите XML-файл описанной выше структурой и настроите отправку в него данных о совершенных действиях пользователей, получите ссылку для тестирования в разделе «Интеграция».

  • 1.1 В личном кабинете перейдите в раздел «Интеграция» (меню → Программа → Интеграция).

    1.2 Затем нажмите «Далее» и на странице «Способы интеграции» переключитесь на вкладку «Кастомная интеграция».

    1.3 На вкладке «Кастомная интеграция» выберите «XML» и нажмите «Далее».

    1.4 Промотайте страницу вниз до блока «Тестирование интеграции» и скопируйте тестовую ссылку из соответствующего поля.

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

  • Значение параметра admitad_uid обрабатывается на всех страницах сайта и сохраняется в cookie.

  • Срок жизни cookie с admitad_uid соответствует сроку, указанному в договоре или, если договора нет, то сроку в 90 дней.

  • Cookie не удаляется при переходе пользователя через органический поиск.
    Чтобы это проверить, при совершении тестового заказа:

    • 1. Сначала перейдите по тестовой партнерской ссылке.
    • 2. Затем перейдите по органической ссылке.
    • 3. Сделайте заказ и проверьте, что он отобразится в системе.

  • Отправка данных в XML-файл работает для всех целевых действий и тарифов вашей партнерской программы.
    Для этого сделайте несколько заказов, чтобы проверить, что в каждом случае трекинг работает корректно.

  • Для каждой товарной позиции в корзине создается свой тег <payment>.

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

3. Затем проверьте другие настройки, если используете их.

  • Если вы используете промокоды Take&Go, сделайте тестовый заказ по следующей схеме:

    • 1. Перейдите на свой сайт по прямой ссылке без параметров.
    • 2. Используйте промокод Take&Go при оформлении заказа и убедитесь, что заказ засчитан Admitad Partner Network.

  • Если вы используете другие платные источники, сделайте тестовый заказ по следующей схеме:

    • 1. Перейдите по партнерской ссылке из другого источника.
    • 2. Перейдите по партнерской ссылке Admitad Partner Network.
    • 3. Сделайте заказ и убедитесь, что он был засчитан Admitad Partner Network.

  • Если у вас есть:

    • мобильная версия сайта,
    • форма быстрого заказа
    • и/или форма заказа в 1 клик,

    проверьте, что трекинг настроен для всех платформ и способов покупки.

4. После того как вы сделаете тестовые заказы, вам нужно сообщить специалистам Admitad Partner Network о том, как получить доступ к XML-файлу с информацией по этим заказам. Специалисты выгрузят и обработают файл в течение 3−4 дней.

5. Если трекинг настроен корректно, в течение часа действия появятся в статистике Admitad Partner Network.

Чтобы проверить это, перейдите в свой личный кабинет Admitad → «Статистика» → «По действиям» и убедитесь, что в статистике корректно отображается целевое действие и данные по нему:

  • название целевого действия в колонке «Тариф» в статистике соответствует названию этого действия в разделе «Действия»;

  • ID действия в колонке «ID заказа» соответствует ID действия в вашей системе;

  • сумма заказа в Admitad соответствует сумме тестового заказа.

integration.png


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

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

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

  • корректно указали все обязательные параметры;

  • использовали в тегах верный регистр.

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

Исправьте ошибку и проведите повторный тест. Подробнее о разделе «Журнал запросов»

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

  • Целевое действие Параметр и его значение Использованный префикс
    Регистрация order_id=reg_123123 reg_
    Получение 5 уровня order_id=lvl5_123123 lvl5_

Вернуться к обязательным параметрам

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