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

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