Хвосты, трекинг и интеграции

Практическая документация для кабинета madpwa.com: хвосты, Keitaro, postback и пиксели.

Коротко: как устроена цепочка

Три ссылки в карточке потока:

1. Хвосты

Что такое хвост

Хвост — query-строка на ссылке запуска. В неё кладут параметры рекламной сети и свои sub*, чтобы они доехали до трекера и в макросы оффера.

Пример (как в кабинете):

https://madpwa.com/n/nk_xxxxxxxx?fbp=PIXEL&ttp=TTP&sub1=SUB1&sub2=SUB2&sub3={{campaign.name}}&sub4={{adset.name}}&sub5={{ad.name}}

В Facebook/TikTok макросы {{…}} подставляет сама рекламная сеть. На выходе получается обычная строка ?sub3=MyCampaign&….

Куда попадает хвост

1. Реклама ведёт на лендинг PWA: GET /a/{slug}?… (преленд → стор → /go). Прямой оффер без воронки: /n/{key} или /a/{slug}/go.
2. На /go (или /n/…) кабинет создаёт click_id, пишет клик в БД (вместе с fbp / fbc / fbclid, если они были в query).
3. Выбирается URL оффера по правилам потока (GEO / платформа / вес).
4. Макросы {clickId}, {sub1}, {campaignName}… раскрываются.
5. Редирект 302 на трекер.

«Добавлять параметры с потока / ссылки запуска» (append_query)

Всегда добавляются служебные: click_id, nk (ключ потока). Params конкретного URL-правила применяются всегда.

Макросы в URL оффера

Пишутся в фигурных скобках:

Алиасы хвоста (часть списка): utm_campaign → campaignName, utm_source → networkSource, ad_id → adId и т.д. Полный набор — в namings.py (NAMING_MACROS, _INCOMING_ALIASES).

Правила URL в потоке

• Список URL сверху вниз: первое подходящее правило (страны, exclude, платформы android|ios|desktop|other, логика AND/OR).
• Несколько подряд совпавших правил — выбор по весу.
• Замыкающая ссылка (closing_url) — если ни одно правило не подошло.
• Первая подходящая (save_first_url) — при нескольких совпадениях брать первую подходящую строку (GEO/платформа всё равно учитываются), без розыгрыша по весу.

Типичный оффер для Keitaro:

https://tracker.example/XXXXX?external_id={clickId}&sub1={sub1}&sub2={sub2}&sub3={sub3}

Без external_id={clickId} постбек не склеит конверсию с кликом.

Код

2. Трекинг

2.1 Клик и атрибуция

В таблице clicks сохраняются: click_id, slug, IP, UA, fbp, fbc, fbclid, naming_key.

Этот click_id и есть то, что трекер должен вернуть в постбеке как subid (через external_id в Campaign URL).

2.2 S2S Postback

Формат как у Skak (полный) или минимальный:

GET /postback?subid={external_id}&tid={tid}&status={status}&payout={conversion_revenue:usd}&sale_status=sale,dep,ftd,deposit,approved&lead_status=lead,reg&currency=usd

GET /postback?subid={external_id}&status={status}&payout=…|sum=…|amount=…

Дополнительно: Web Push по slug PWA, запись в stats_events, CAPI с сохранёнными fbp/fbc/fbclid клика.

В Keitaro → Source → S2S Postback — та же схема, что Skak, хост madpwa.com. Подробный копипаст: §3.

{external_id} в Keitaro — это наш click_id.

2.3 Пиксели в браузере + клиентские события

На store / preland / white (по настройкам) в <head> попадает HTML из metrics.head_html().

Клиентский скрипт (landings.install_script):

• ping('install'|'clicks'|'leads') → POST /api/pwas/{slug}/event
• fbq('track', …) / twq(…) с eventID
• читает cookies _fbp, _fbc, query fbclid

Карта событий по умолчанию (настраивается на PWA):

Пиксели задаются в карточке PWA: fb_pixels (pixel_id + access token), tw_pixels (Track ID + API key). Без токена — только браузер; с токеном — ещё и CAPI.

2.4 Лог «События Ads»

• Отправка CAPI в фоне (metrics.fire)
• Лог: data/metrics-capi-log.jsonl (или путь из PWA_METRICS_LOG)
• Кабинет: список через GET /api/ads-events, тест — POST /api/pwas/{id}/metrics/test

2.5 Статистика воронки

stats.py — виды: visit, open, install, reg, dep, push_*. На install списывается CPI (CPI_CENTS, по умолчанию 2 цента = $0.02).

2.6 Клоака

cloak.py: боты / VPN / hosting → white-страница. Страна: заголовок Cloudflare CF-IPCountry или ip-api.com. Настройки PWA: bot_hosting, bot_proxy, tiktok_source, pixel_on_white, white_url и др.

3. Как настроить Keitaro (как у Skak)

Схема та же, что у Skakapp: реклама → наш `/n/…` → Keitaro → оффер → S2S postback → нам. Мы не шлём конверсии в Keitaro — Keitaro шлёт их нам на /postback.

madpwa ≈ Skak: что совпадает

Отличия: другой домен postback; у Skak ещё from=client_ID_SKAK (у нас не нужен). Остальное можно копировать 1-в-1.

Готовые ссылки (копипаст)

1) Keitaro → Edit Source → S2S postback

Как у Skak, только хост наш:

https://madpwa.com/postback?subid={external_id}&tid={tid}&status={status}&payout={conversion_revenue:usd}&sale_status=sale,dep,ftd,deposit,approved&lead_status=lead,reg&currency=usd

Минимальный вариант:

https://madpwa.com/postback?subid={external_id}&status={status}

Send only statuses: Lead + Sale (как на скрине Skak).

2) Keitaro → Edit Source → Parameters (шаблон как Skak)

В колонке Parameter / Placeholder — то, что Keitaro допишет к Campaign URL. Справа — макросы madpwa (их раскроет наш /n/… при редиректе на трекер).

Критично: строка External ID = external_id / {clickId} — без неё postback не склеится.

3) Кабинет → поток → URL оффера

Вставьте Campaign URL из Keitaro (после сохранения Source параметры уже в шаблоне). Должно получиться примерно так:

https://ВАШ-ТРЕКЕР/XXXXX?external_id={clickId}&source={networkSource}&ad_campaign_id={campaignId}&sub1={sn_sub1}&sub2={sn_sub2}&sub3={sn_sub3}&sub4={sn_sub4}&sub5={sn_sub5}&campaign_name={campaignName}&fbp={sn_fbp}&fbclid={sn_fbclid}&country={country}&os_name={osName}

«Добавлять параметры» = Да.

4) Реклама — только «С хвостом»

https://madpwa.com/n/nk_xxxxxxxx?fbp=PIXEL_ID&ttp=TTP&sub1=SUB1&sub2=BUYER&sub3={{campaign.name}}&sub4={{adset.name}}&sub5={{ad.name}}

{{…}} — макросы FB/TikTok. Нельзя кидать в Ads сырой Campaign URL Keitaro.

Что куда (кратко)

Шаг за шагом

1. Keitaro → Sources → New / Edit

- S2S postback = ссылка madpwa из блока «Готовые ссылки». - Send only: Lead + Sale. - Parameters: External ID → external_id = {clickId} (+ остальные по таблице).

1. Кампания Keitaro на этом Source → скопировать Campaign URL.
2. Кабинет → Потоки → в оффер вставить Campaign URL; append_query = Да; сохранить.
3. PWA → выбрать поток; Метрики → pixel + token.
4. В Ads — «С хвостом».
5. Прогон теста (ниже).

Как прогнать тест (когда всё добавили)

A. Ручной тест postback (30 секунд)

1. Открой ссылку «С хвостом» из карточки потока (или чистый /n/ключ) в браузере.
2. DevTools → Network → найди 302 на трекер. В URL скопируй значение external_id= (это наш click_id).
3. В новой вкладке открой (подставь свой id):

https://madpwa.com/postback?subid=СКОПИРОВАННЫЙ_EXTERNAL_ID&status=lead

Должно вернуть {"ok":"1"}.

1. Для депозита:

https://madpwa.com/postback?subid=СКОПИРОВАННЫЙ_EXTERNAL_ID&status=sale&payout=10&currency=usd

1. Проверь в кабинете:

- у PWA вырос leads / deps; - раздел События Ads — строка CAPI (если есть Access Token у пикселя).

Без живого клика (external_id из шага 2) postback придёт, но не привяжется к PWA — счётчики не вырастут.

B. Тест из Keitaro

1. Сделай тестовый клик по «С хвостом» → клик появится в Keitaro с External ID.
2. В Keitaro на этом клике / конверсии отправь тестовый Lead (или Conversion → Lead).
3. Keitaro дернет наш S2S URL сам.
4. Снова проверь счётчики + «События Ads».

C. Тест пикселя без Keitaro

В карточке PWA → Метрики → кнопка Тест (install / reg / dep) — шлёт CAPI напрямую. Это проверка token/pixel, не склейки с трекером.

Маппинг status → события

Если в postback заданы sale_status=… и lead_status=… — кабинет смотрит на эти списки (как Skak).

Частые ошибки

Короткий чеклист

1. Source S2S = madpwa postback (Skak-формат).
2. Parameters: external_id = {clickId}.
3. Поток: Campaign URL + append_query Да.
4. Ads: только «С хвостом».
5. Тест postback status=lead.

4. Интеграции

Реклама и атрибуция

Любой трекер с S2S и external_id работает по той же схеме, что Keitaro. Отдельной интеграции Binom в коде нет.

Пуши и мессенджеры

Домены и инфраструктура

Прочее

5. Переменные окружения

На проде секреты: /etc/pwa-cabinet.env (см. deploy/pwa-cabinet.service). Пиксели, потоки, токены CAPI — в SQLite (pwas, namings), не в env.

6. Словарь RU ↔ код

7. Ключевые файлы

https://madpwa.com/docs/tracking · алиас /docs/keitaro