Интеграция через postback-запрос

  • Обновлено

При интеграции через postback-запрос ваш сервер отправляет запрос с данными о совершенных на вашем сайте действиях серверу Admitad Affiliate.

Сервер Admitad Affiliate забирает эти данные и загружает их в статистику.

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

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

  • Изменения на сайте не затрагивают отправку запросов через postback.
  • Более безопасный тип интеграции, т.к. в запросе есть приватный ключ авторизации. Кроме того, отправка запросов идет с заранее известных вам IP-адресов, и источник запросов можно проверить в любой момент по логам.
  • Есть готовые плагины для интеграции с магазинами на платформе популярных CMS (1С-Bitrix, Shop-Script, WooCommerce, OpenCart, InSales).
  • Для реализации решения необходим доступ к серверной части сайта (back-end).
  • При наличии мобильной версии сайта или мобильного приложения, форм быстрого заказа или заказа в 1 клик их также необходимо проинтегрировать.
  • Postback-запрос отправляется непосредственно с вашего сервера, а не с клиентской стороны (браузер пользователя).
  • Postback-запрос должен отправляться только для действий пользователей, пришедших от 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 есть, значение необходимо передать в postback-запрос.

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

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

Интеграция через postback-запрос 1

 

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

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

2. Реализация алгоритма чтения admitad_uid из cookie и записи в базу данных при авторизации пользователя.

3. Реализация механизма отправки postback-запроса с вашего сервера (например cURL, Wget, file_get_contents).

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

5. Подстановка этих значений в массив параметров postback-запроса.

Специального ответа сервера Admitad Affiliate на postback-запрос нет. Возвращается статус HTTP 200 OK.

Запись 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'];
}

 

Настройка postback-запроса

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

Имя параметра
(курсивом выделены алиасы)

Описание Тип Примечание
uid идентификатор Admitad Affiliate строка

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


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


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

campaign_code код программы строка, 10 символов константа, значение определено в postback-запросе, отправленном вам в начале интеграции

order_id, oid

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

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

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

action_code, ac, product, product_code

код целевого действия целое число переменная, значение сообщает специалист отдела трекинга в начале интеграции
tariff_code, tc код тарифа целое число переменная, значение сообщает специалист отдела трекинга в начале интеграции
currency_code, currency, c код валюты строка, 3 символа определяется в ISO 4217; принимаются только буквенные значения
position_id, pid  номер позиции товара в корзине целое число переменная, значение изменяется от 1 до N, где N = position_count
position_count, pc, pn количество позиций в корзине целое число переменная, значение N, зависит от состава корзины, оформленной пользователем
payment_type тип целевого действия строка, 4 символа константа, значение sale/lead
product_id, prid ваш внутренний ID товара строка, 1-100 символов ваш внутренний ID товара, должен соответствовать ID из товарного фида
quantity количество единиц товара в позиции целое или дробное число  
postback, pb ключ для авторизации postback-запроса строка, 1 символ константа, значение 1
postback_key, postback_hash, pk ключ идентификации postback-запроса строка, 32 символа константа, значение определено в postback-запросе, отправленном вам в начале интеграции
price, cart, p, amount стоимость одной позиции товара в корзине целое или дробное число  

 

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

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

К примеру, у компании-туроператора отсутствуют параметры, отвечающие за разбивку по корзине, а есть только стоимость тура и номер заказа. Тогда обязательными параметрами будут order_id и price, а параметры position_id и position_count будут отсутствовать.

Уточнить, какие параметры являются обязательными конкретно в вашем случае, вы можете у своего аккаунт-менеджера.

Пример postback-запроса для корзины с несколькими товарными позициями

Товарная позиция

Наименование товара

Цена Количество товара

Сумма товарной позиции

1 TV 20 000 2 40 000
2 iPhone 35 000 3 105 000
3 Notebook 50 000       1 50 000
      Итого 195 000
  • https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
    &action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
    &price=20000&quantity=2&position_id=1&position_count=3&product_id=11&client_id=&payment_type=sale
    
    https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
    &action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB&
    price=35000&quantity=3&position_id=2&position_count=3&product_id=21&client_id=&payment_type=sale
    
    https://ad.admitad.com/r?campaign_code=your_campaign_code &postback=1&postback_key=your_postback_key
    &action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
    &price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale

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

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

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

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

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

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

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

 

Пример postback-запроса для заказа с уникальным промокодом

  • https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
    &action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
    &price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale
    &promocode=admitad500

3. Убедитесь, что все заказы с уникальным промокодом отправляются в Admitad Affiliate.

В Admitad Affiliate заказ должен передаваться в следующих случаях:

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

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

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

1. После того как вы настроите алгоритм отправки postback-запросов с сервера, свяжитесь с отделом трекинга Admitad Affiliate и запросите партнерскую ссылку для тестирования.

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

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

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

Интеграция через postback-запрос 2

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

4. Если действие не появилось в статистике в течение часа, проблема либо в неверной реализации механизма отправки запроса, либо в неверных параметрах запроса. Убедитесь, что:

  • вы не допустили ошибок при реализации механизма отправки postback-запросов;
  • в запросе именно те campaign_code и postback_key, которые были вам отправлены в начале интеграции.

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

Интеграция с помощью плагинов

Если ваш магазин создан на платформе 1С-Bitrix, Shop-Script, WooCommerce, OpenCart или Magento, вы можете использовать соответствующий плагин для быстрой интеграции с Admitad Affiliate. Подробнее об этом читайте в статье «Интеграция через плагины».

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