Click API и SDK¶

Способы работать с трекером не через браузерный редирект.

Click API¶

Программный клик без браузера: тот же пайплайн выбора потока, лендинга и оффера, что и обычный редирект, но вход и выход — JSON.

curl -X POST https://tr.example.com/click-api/v3 \
  -H "Authorization: Bearer ak_ВАШ_КЛЮЧ" \
  -H 'Content-Type: application/json' \
  -d '{
        "campaign": "abc123",
        "ip": "203.0.113.10",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "sub_ids": {"sub1": "creative_42"}
      }'

В ответе — конечный URL вместо HTTP-редиректа: click_id, destination, campaign_id, flow_id и, если они выбраны, landing_id с offer_id.

Ключ выпускается в API-ключах, нужен scope write. Без него — 403 insufficient scope.
Ключ работает только с кампаниями своего воркспейса: чужой alias вернёт 403, даже если угадан правильно.
Лимит — 200 запросов в секунду на IP, всплеск до 1000; лимит общий с MClient. Тело запроса — до 64 КиБ.
Передавайте IP и User-Agent конечного пользователя явно, иначе гео и фильтры посчитаются по вашему серверу.

Контракт v3 умеет только редирект

Если поток закончился не переходом — безопасная страница, 404, текст или HTML, — выразить это в ответе нечем, и запрос получает 404 no matching flow. Клик при этом уже обработан: счётчики кампании и потока по нему засчитаны.

Полное описание полей — в справочнике (переключатель вверху слева → Click API).

LP SDK¶

Скрипт minik.js и PHP-хелпер minik.php для страниц, которые хостятся не в трекере. Позволяют странице самой спросить у трекера, какой оффер показывать, и отправить события. Оба файла раздаёт сам трекер: GET /sdk/minik.js и GET /sdk/minik.php.

Что даёт:

GET /lp-api/offer?cid=<click_id> — отдаёт offer_url, выбранный ещё на клике, чтобы кнопка на странице вела на нужный оффер;
POST /action — событие lead / sale / signup либо custom со своим статусом;
GET /px.gif — та же конверсия картинкой, для страниц без JavaScript.

Подключённый с атрибутом data-minik-auto скрипт разбирает разметку сам: data-minik-offer подставляет URL оффера в href, data-minik-action на кнопке или форме отправляет событие, data-minik-thankyou на <body> — при открытии страницы.

Готовый сниппет для вставки генерируется в карточке кампании и в редакторе лендингов — копируете и вставляете.

Повторы гасятся: ключом служит txid, а если его не передали — сам тип события. Перезагруженная страница благодарности конверсию не удвоит.

Как аутентифицируется конверсия из браузера¶

/action и /px.gif открыты наружу, поэтому конверсия подписывается пер-клик токеном. Трекер выдаёт его на редиректе: внешнему лендингу — во фрагменте #_ct=… (фрагмент не уходит ни в Referer, ни на домен оффера), лендингу внутри трекера — в cookie _mtoken. minik.js и minik.php подставляют токен сами, вручную ничего делать не нужно.

Конверсия без валидного токена записывается, но наружу не уходит — ни в CAPI, ни в вебхуки, ни исходящим постбэком. С MINIK_CONV_TOKEN_ENFORCE=1 она отклоняется совсем: /action отвечает 403, px.gif по-прежнему отдаёт картинку, но ничего не пишет.

Payout из браузера не принимается

Сумма и валюта для /action и /px.gif берутся из оффера, выбранного на клике, — параметр payout в этих вызовах игнорируется. Иначе выручку мог бы выдумать кто угодно. Сумму от партнёрки принимает только серверный постбэк.

MClient¶

Remote-execution: внешний сайт зовёт трекер вместо того, чтобы редиректить на него. Посетитель остаётся на вашем домене, а решение о маршрутизации всё равно принимает трекер.

Компоненты: mclient.js / mclient.php (GET /sdk/mclient.js, GET /sdk/mclient.php) и эндпоинт POST /mclient/v1. Лимиты те же, что у Click API: 200 запросов в секунду на IP, тело до 64 КиБ.

Вызов подписывается токеном кампании — он показан в её карточке рядом со сниппетом. Без токена трекер отвечает do_nothing и не раскрывает, существует ли такой alias вообще. JS-клиент отдаёт токен в исходнике страницы, так что секретом он остаётся только для серверного PHP-клиента.

В ответе — решение: action (redirect, show_landing, show_offer, do_nothing, show_404, show_text, show_html), destination, offer_url, is_bot, is_unique, reason; для show_text и show_html — готовое тело страницы в body.

Ограничение

Потоки со схемой action script через Click API и MClient не исполняются — такой клик маршрутизируется лендингами и офферами потока.

Конверсии MClient отправляет на тот же /action, но пер-клик токена у такой страницы нет: посетитель не проходил через редирект трекера. При MINIK_CONV_TOKEN_ENFORCE=1 эти конверсии будут отклоняться — для сайтов на MClient используйте серверный постбэк.

Симулятор¶

Трекинг → Симулятор. Генератор синтетического трафика: клики с заданными гео, устройствами, долей ботов и конверсиями. Нужен, чтобы проверить фильтры, ротацию и отчёты до боевого запуска.

Строки пишутся прямо в ClickHouse, минуя HTTP, кеш и cookies, и помечаются is_simulated=1. За один запуск — до 100 000 кликов.

Отчёты по умолчанию симулированный трафик прячут: чтобы его увидеть, включите переключатель Симуляция (после запуска симулятор включает его сам). Кнопка очистки удаляет только помеченные строки, реальные данные не трогает.

Метрики Prometheus¶

GET /metrics — экспорт в формате Prometheus: латентность редиректа и action-скрипта (гистограммы), счётчики кликов и конверсий, дубли и неатрибуцированные конверсии, состояние очередей и потери данных, исходящие S2S, плюс go_goroutines и память процесса. Меток по кампаниям и воркспейсам нет — это метрики процесса, а не отчёт.

Авторизации у эндпоинта нет, поэтому его закрывают сетью:

Caddy из установщика отдаёт на /metrics* снаружи 404;
INTERNAL_DENY_CIDR закрывает путь изнутри — из подсети, где крутится PHP лендингов и action-скриптов.

Собирайте метрики из внутренней сети — например, Prometheus в той же docker-сети по http://server:8080/metrics.