Postback

Postback — это HTTP-запрос, который отправляется с сервера рекламодателя (партнерской сети, собственного сайта) на сервер трекера, чтобы сообщить о факте совершения конверсии.

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

Для записи конверсии в статистику трекер использует идентификатор клика subid и статус конверсии status — обязательные параметры postback.

Способы отправки Postback

Конверсии передаются в трекер следующими способами:

1. Партнерской сетью или прямым рекламодателем.

2. Скриптами трекера — KClient PHP и Скрипт отслеживания — с сайтов на сторонних хостингах, когда трафик идет напрямую на домен сайта, без партнерской сети.

3. С помощью JS-Adapter — с локальных сайтов, добавленных в трекер как архивы, или с редирект-сайтов. Вариант подходит для личного сайта, а не для партнерской сети.

Обработка входящего Postback

Трекер принимает postback, ищет клик по subid и проверяет параметр status. При корректных данных конверсия записывается в статистику. При отсутствии status или при неизвестном статусе без сопоставления запрос игнорируется.

Получение Postback URL трекера

Postback URL — ссылка, на которую рекламодатель, партнерская сеть или сайт передает данные о конверсии в трекер.

Получение Postback URL для партнерской сети описано в разделе Postback партнерской сети.

В ссылке указываются:

• Адрес сервера трекера;
• Postback key — уникальный идентификатор для безопасности и аутентификации запроса postback;
• Параметры конверсии.

Для получения Postback URL:

1. Откройте Настройки → Postback URL.

2. Скопируйте Postback URL.

3. При необходимости добавьте в ссылку параметры из раздела Параметры Postback.

Дополнительные имена параметров для Postback

В разделе Postback URL → Параметры настраиваются дополнительные имена параметров Postback.

Настройка подходит для случаев, когда партнерская сеть передает идентификатор клика или другие данные в параметрах с именами, отличными от стандартных subid, status, payout, tid, date.

Например, трекер одинаково обработает оба варианта:

http://IP/postback-key/postback?subid=REPLACE&status=REPLACE&payout=REPLACE

http://IP/postback-key/postback?clickid=REPLACE&type=REPLACE&profit=REPLACE

Для корректной обработки укажите дополнительные имена параметров в колонке Алиас.

Параметры Postback

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

• subid. Идентификатор клика в трекере. По данному параметру трекер определяет, на какой клик записать конверсию.
• status. Статус конверсии. Список базовых статусов указан в разделе типы конверсии Keitaro.

Без параметров subid и status трекер не сможет корректно обработать postback.

Дополнительные параметры

• tid. ID транзакции. Используется для записи повторных конверсий без перезаписи предыдущей.
• payout. Сумма выплаты по конверсии. Поддерживаются положительные и отрицательные значения.
• cost. Стоимость конверсии для CPA и RevShare моделей расходов.
• currency. Валюта выплаты, например usd, eur, rub.
• sub_id_1 - sub_id_30. Дополнительные параметры для обновления данных клика. Поддерживаются строковые и числовые значения.
• return. Текст ответа отправителю. Например, &return=OK вернет OK при успешной обработке postback.

WARNING

Допускается передача параметров keyword, cost, external_id, creative_id, ad_campaign_id и source, но полученные значения перезапишут данные, ранее записанные с кликом из источника трафика.

TIP

При повторной отправке postback с аналогичным subid и измененными параметрами трекер перезапишет предыдущую конверсию.

При полном совпадении параметров postback обработается, но S2S-postback повторно не отправится.

Типы конверсий

Keitaro поддерживает следующие типы конверсий и отображает их в отчётах:

• Lead — лид. Выплата не подтверждена. Доход отображается в метрике Доход (ожидаемый).
• Sale — продажа. Выплата подтверждена. Доход отображается в метрике Доход (подтвержденный).
• Rejected — отмена конверсии. Выплата отменена. Доход отображается в метрике Доход (отклоненный).
• Registration — регистрация. Доход отображается в метрике Доход (регистрация).
• Deposit — депозит. Доход отображается в метрике Доход (депозиты).
• Trash — нерелевантная конверсия. Доход отображается в метрике Доход (trash).
• Пользовательские типы конверсий — дополнительные типы конверсий для точного анализа статистики.

Когда postback игнорируется

• При отсутствии параметра status трекер игнорирует postback и записывает соответствующую запись в лог.

• При передаче статуса, который не поддерживается трекером и для которого не заданы параметры обучения, трекер игнорирует postback и записывает соответствующую запись в лог.

Обучение нестандартных статусов

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

Keitaro принимает любое значение в параметре status и относит его к необходимому типу конверсии при корректно заданном обучении.

Для обучения используются параметры:

• lead_status
• sale_status
• rejected_status
• registration_status
• deposit_status
• trash_status
• custom*_status — где custom* необходимо заменить на параметр созданного пользовательского типа конверсии.

Пример

Партнерская сеть передает регистрации со статусами new и registered.

Для записи данных конверсий как Registration добавьте в ссылку postback следующее обучение:

status=new&registration_status=new,registered&sale_status=billed&rejected_status=canceled,fake

При получении конверсии со status=new или status=registered трекер отнесет её к типу конверсии Registration согласно обучению, указанному в ссылке: status=new&registration_status=new,registered.

Оригинальный статус, переданный партнерской сетью, сохраняется в колонке Статус в логе конверсий.

Запись повторных конверсий

Если в трекер последовательно отправляются два postback с одинаковым статусом, ранее зафиксированная конверсия перезаписывается новой.

Чтобы конверсия записывалась как дополнительная, а не заменяла существующую, в ссылку postback необходимо передавать уникальное значение в параметре tid.

Например, при последовательной отправке двух postback со следующими параметрами:

status=sale
status=sale&tid=2

В отчет попадут две отдельные конверсии со статусом Sale, вместо перезаписи одной.

Конвертация валюты

Трекер хранит статистику в одной валюте, указанной в Настройки → Основные → Валюта.

Для конвертации суммы выплаты передавайте валюту в Postback URL через параметр currency. При получении postback трекер конвертирует сумму выплаты в валюту, указанную в настройках.

Пример:

https://example.com/key/postback?status=lead&payout=10&currency=EUR

Валюта статистики задается на уровне трекера и используется для всех кампаний.

Отправка postback с помощью postback pixel

Postback Pixel — фрагмент кода на странице, передающий в трекер данные о конверсии после целевого действия.

Подходящий вариант для пользовательского кода на сайте, когда конверсия отправляется со страницы, а не со стороны партнерской сети.

1. Используйте локальный лендинг, локальный оффер или предзагрузку. Подробности о требованиях к созданию лендингов и офферов смотрите на странице Лендинг: локальный.

2. Добавьте код Postback Pixel между тегами <body>...</body> на странице index.html или index.php:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

Вместо POSTBACK_URL укажите ссылку из раздела Настройки → Postback URL.

WARNING

Макрос {subid} в ссылке postback работает только на страницах index.html или index.php.

1. Создайте оффер или лендинг с действием редирект. В параметрах URL передавайте subid={subid}:

2. Добавьте код Postback Pixel между тегами <body>...</body> на странице и обработайте значение {subid}, переданное в параметре subid= в ссылке на сайт:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

Пример обработчика {subid} с пикселем:

<script>
        document.addEventListener('DOMContentLoaded', () => {
            const urlParams = new URLSearchParams(window.location.search);
            const subid = urlParams.get('subid');
            const postbackUrl = `POSTBACK_URL?subid=${subid}&status=lead&payout=10&currency=usd`;
            document.getElementById('postback-pixel').src = postbackUrl;
        });
</script>

<img id="postback-pixel" src="" width="1" height="1" />

Вместо POSTBACK_URL укажите ссылку из раздела Настройки → Postback URL.

Postback FAQ

Почему не отображаются конверсии?

Смотрите Устранение проблем с postback.

Как Keitaro конвертирует валюту?

Keitaro ежедневно дважды в сутки запрашивает курсы валют у внешнего сервиса.

Почему тестовый postback от партнерской сети не срабатывает?

Партнерские сети в тестовых postback не передают реальный subid клика.

Для проверки настройки postback выполните целевое действие по ссылке кампании и дождитесь отправки реального postback.

Как изменить Postback key?

Postback key — уникальная строка для защиты трекера от поддельных postback-запросов.

Для замены postback key укажите новое значение в конфиге /etc/keitaro/env/inventory.env:

TRACKER_POSTBACK_KEY=CUSTOM_KEY

После изменения запустите переконфигурацию системы:

kctl tune