Развернуть трекер Keitaro на VPS: Docker, атрибуция и аналитика

Перед установкой Keitaro на VPS полезно собрать в одном месте то, без чего настройка начнёт «сыпаться»: домены, доступы, базовую сетевую схему и понимание, как будет происходить атрибуция конверсий.

Минимально стоит решить четыре вопроса.

• Где будет жить интерфейс трекера и клики: ваш домен трекера, например tracker.example.com
• Где будет принимать конверсии ваш лендинг или прокладка между лендингом и трекером
• Какой тип аналитики подключаете: Яндекс Метрика, Google Analytics, CRM, сквозная аналитика (все они чаще всего принимают события через postback или вебхуки)
• Какие идентификаторы вы будете использовать для сопоставления клика и конверсии: UTM-параметры, subid, gclid/fbclid, internal click_id и так далее

По окружению обычно берут Ubuntu Server (часто LTS) и выделяют VPS с понятным запасом по памяти. Keitaro хорошо чувствует себя на обычных конфигурациях, но если вы планируете много кликов и тяжёлые правила редиректа, лучше не экономить на RAM и IOPS. Важно также, чтобы выход в интернет с VPS был стабильным: постбеки и запросы к внешним сервисам никуда не исчезают.

Ещё одна практичная вещь: заранее продумайте DNS. Вам понадобятся записи для домена трекера (A/AAAA или CNAME), а также иногда отдельный поддомен для целей, если вы разводите конверсии и редиректы. Логи и трассировка в будущем сильно упростятся, если всё будет на одном доменном контуре.

Развертывание Keitaro на VPS: варианты установки и пошаговая схема

Keitaro можно развернуть несколькими способами, но для большинства сценариев удобнее контейнерная установка. Контейнеры дают воспроизводимость: вы переносите окружение как конфиг, а не как набор «поставил и забыл».

Ниже логика подойдёт под установку через Docker и docker-compose. Точные команды и версии зависят от текущего способа поставки, поэтому ориентируйтесь на официальный репозиторий/документацию Keitaro для вашего билда.

1) Подготовьте VPS и базовую безопасность

Начните с базовой гигиены.

• Обновите систему и поставьте утилиты для диагностики (curl, tar, unzip, lsof при необходимости)
• Настройте firewall (часто достаточно открыть только SSH и HTTP/HTTPS, остальное закрыть)
• Создайте отдельного пользователя для работы, если вы заходите в систему не root

Если вы планируете использовать Let’s Encrypt, убедитесь, что домен трекера доступен из интернета и не блокируется провайдерами. Проверка простая: с локальной машины откройте в браузере ваш будущий tracker-домен, когда он появится в DNS.

2) Разверните Keitaro в контейнерах

Ключевой принцип такой: развернуть единый набор сервисов, где Keitaro связан с хранилищем (БД) и веб-слоем (часто это nginx/прокси внутри композиции).

Обычно docker-compose поднимает:

• сервис Keitaro (приложение)
• сервис БД
• reverse proxy (если он заложен в схему)

Дальше действуете по шаблону:

1. Скачайте шаблон docker-compose из официального источника
2. Отредактируйте конфиг под ваш сервер: порты, переменные окружения, тома для данных
3. Пропишите тома для БД и для папок с конфигами/логами, чтобы контейнеры не «съедали» данные при пересоздании
4. Запустите docker-compose
5. Проверьте доступность интерфейса по домену трекера

Важно: не держите секреты в открытом виде в репозитории и на общих серверах. Если окружение позволяет, выносите токены и пароли в переменные окружения docker-compose или в секреты.

3) Настройте HTTPS и проксирование

Даже если трекер стартует по HTTP, для рабочих связок лучше сразу включить HTTPS. Причины практические:

• многие рекламные платформы чувствительны к редиректам и запросам
• браузеры не любят смешанный контент (особенно когда на лендинге есть скрипты)
• постбеки и callback-URL проще отлаживать, когда они консистентны

Чаще всего делают так:

• reverse proxy слушает 80/443
• на 443 включают SSL-сертификат
• Keitaro сервис доступен только внутри docker-сети, а наружу торчит nginx

Если в вашей схеме Keitaro сам умеет HTTPS, всё равно проверьте корректную передачу заголовков (Host, X-Forwarded-Proto). Это влияет на формирование ссылок и редиректов.

4) Базовая проверка: что проверить в первые 15 минут

Перед тем как лезть в атрибуцию, убедитесь, что базовая связка работает.

• Интерфейс Keitaro открывается и логинится
• Редирект по тестовой ссылке отдаёт целевой URL
• Запрос конверсии (если вы добавили тестовый goal) доходит до трекера
• Постбек во внешнюю систему (даже на заглушку) возвращает ожидаемый статус

Лайфхак: добавьте в аналитику один простой endpoint на приём POST/GET и логируйте входящие параметры. Это быстрее, чем пытаться понять, где «ломается» UTM уже на этапе сложной интеграции.

Настройка трекинга: домен трекера, посадочные редиректы и правила

Настройка Keitaro почти всегда начинается с «контура клика»: как пользователь попадает на лендинг через трекер и какие параметры несёт этот переход.

Keitaro обычно оперирует сущностями вроде кампаний/офферов/правил редиректа и параметров, которые вы передаёте в ссылку. Названия экранов могут отличаться в зависимости от версии, но логика одна.

Домен трекера и что пользователю реально показывается

Есть два популярных подхода:

• трекер редиректит на лендинг, а пользователю не видно технических параметров
• на лендинге держится часть трекинга (скрипт/пиксель Keitaro), который по факту фиксирует событие

Чтобы атрибуция была стабильной, редирект должен передавать те же идентификаторы, которые вы используете для сопоставления клика и конверсии. На практике чаще всего это набор UTМ и subid.

UTM и subid: какие параметры стоит «нести» дальше

Схема такая: рекламные платформы передают UTM-метки и/или свои идентификаторы, а трекер хранит их вместе с кликом. Позже эти значения нужны, чтобы корректно отдать событие в аналитику.

Минимальный набор, который обычно помогает и не разрастается:

• utm_source
• utm_medium
• utm_campaign
• utmterm и utmcontent (если используете разбор по ключам/креативам)
• subid или его аналоги (для вашего внутреннего разреза: паблишер, оффер, поток, вариант лендинга)

Если вы используете gclid/fbclid, храните их отдельно. Это часто самый надёжный идентификатор рекламного клика у крупных платформ.

Правила редиректа: как не утонуть в ветвлениях

Правила в Keitaro удобны, но есть риск сделать «простую логику» в виде десятков условий, которая в итоге не масштабируется и ломается от мелких изменений.

Хорошая стратегия:

1. Разделите трафик по источникам (source/medium) или по основным идентификаторам
2. Внутри источника используйте ограниченный набор условий: GEO, время, субид, тип устройства
3. Всё, что касается экспериментов по лендингам, выносите в конфигурацию кампаний/офферов, а не плодите отдельные правила на уровне трекера

Для проверки работоспособности берите тестовый набор ссылок. Это 10–20 комбинаций, где вы заранее знаете, какие субпараметры попадут в цель. Потом гоняете их при любых изменениях.

Убедитесь, что конверсия вызывает трекер, а не только лендинг

Есть две модели:

• конверсия отправляется в Keitaro из лендинга (скриптом/коллбеком/формой)
• конверсия подтверждается событием через серверную интеграцию (через ваш backend, webhook или CRM)

Какую бы вы ни выбрали, важно, чтобы Keitaro получал событие с тем же контекстом, что был у клика. Иначе атрибуция получится «по памяти», а не по данным.

На уровне практики это означает: в обработчик конверсии должен попадать click context (например, идентификатор клика или субид, который вы сохраняете в cookie или в скрытых полях). Если этого нет, постбек в аналитику вы отправите, но сопоставление будет слабым.

Связка с внешней аналитикой: postback и вебхуки от Keitaro

Интеграция с аналитикой почти всегда опирается на один и тот же механизм: Keitaro при наступлении события (conversion/goal) вызывает внешний URL и передаёт параметры события.

У внешних систем это называется по-разному: postback, вебхук, callback, server-to-server event. Для вас важно не название, а стабильный контур:

• Keitaro фиксирует конверсию
• Keitaro отправляет запрос на endpoint аналитики/CRM
• endpoint подтверждает приём
• вы проверяете, что в аналитике событие «село» в нужную витрину (кампания/источник/поток)

Что отправлять во внешнюю аналитику для корректной атрибуции

Минимум обычно нужен такой:

• идентификаторы конверсии: transaction/order_id (чтобы не было дублей) или internal goal id
• признаки времени: timestamp конверсии
• идентификаторы клика/атрибуции: clickid, subid, utm* (какой набор вы храните)
• параметры ценности: revenue/amount/status, если аналитика поддерживает деньги
• дополнительные поля: device, country, offerid, landingid (если полезны для разбора)

Если вы отправляете только факт конверсии без контекста, внешний сервис сможет показать «конверсию», но не сможет нормально атрибутировать её в разрезе кампаний. Поэтому в интеграцию стоит включать именно те поля, по которым вы строите отчёты.

Атрибуция по клику vs по событию: выберите модель осознанно

Есть два подхода к атрибуции.

1. Атрибуция по клику: вы отправляете события, привязанные к параметрам клика. Обычно это даёт более управляемый результат.
2. Атрибуция по событию: вы фиксируете данные уже на этапе конверсии (например, что видит браузер). Но тогда вы чаще упираетесь в cookie/consent/ограничения.

Когда вы строите server-to-server постбек из Keitaro, вы чаще приходите к модели «по клику». Keitaro уже знает, по какой ссылке пришёл пользователь и какие subid были в клике.

Интеграция с Яндекс Метрикой: общий принцип и шаблон параметров

У Метрики есть приём событий через HTTP-запросы. Для связки с Keitaro обычно используют Goal ID/метод отправки, а также передают нужные параметры в запрос.

Практическая схема такая:

1. В Keitaro создаёте правило/действие, которое срабатывает при конверсии
2. Настраиваете URL postback на endpoint Метрики
3. В шаблоне URL подставляете переменные из контекста клика и конверсии

Шаблон логики (без привязки к конкретным именам параметров, потому что они зависят от вашей цели и текущей реализации):

• counter_id: идентификатор счётчика
• goal_id: ваша цель в Метрике
• в дополнительные поля кладёте utm_* и subid
• в revenue/amount кладёте сумму, если вы её считаете

Лайфхак для отладки: сначала отправьте тест на один goal и посмотрите в Метрике, что значения UTM пришли как вы ожидали. Только после этого включайте деньги и сложные поля. Тогда, если что-то не доедет, вы поймёте причину быстрее.

Интеграция с Google Analytics: Measurement Protocol и передача идентификаторов

Google Analytics чаще интегрируют через Measurement Protocol: событие отправляется на сервер Google в формате HTTP. Для Keitaro логика похожа: при конверсии сформировать запрос с параметрами и отправить на endpoint GA.

Чтобы атрибуция не «поплыла», вам важно:

• передавать идентификатор пользователя/клиента, который GA использует для связки с визитом (client_id или аналог)
• передавать параметры кампании (utm*, campaignid) и идентификаторы клика, если они у вас есть
• избегать отправки событий без контекста, иначе GA будет относить конверсию к «неизвестным»

На практике чаще всего вы в Keitaro храните subid и UTМ и затем используете их в качестве параметров события. Идентификаторы кампании для ваших внутренних отчётов вы сможете восстановить, но автоматическая склейка именно с визитом GA может зависеть от того, есть ли на стороне лендинга соответствующие идентификаторы.

Если вы строите отчётность в Google Analytics строго по покупкам, проверьте, что client_id реально появляется в вашей схеме. Если его нет, нередко лучше опереться на вашу внутреннюю витрину (через CRM/таблицы) и оставить GA как дополнительный источник.

Практический критерий «готово или нет»

Связка считается рабочей, если одновременно выполняются условия:

• в Keitaro конверсия отмечена один раз (или ваш механизм дублей контролирует повторы)
• внешний сервис принимает событие и показывает его в нужной цели/событии
• по каждому событию можно однозначно восстановить, из какого клика и кампании оно произошло (через UTM/subid/click_id)

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

Атрибуция конверсий: как не потерять ключи и правильно сопоставить события

Атрибуция ломается обычно не из-за «плохого трекера», а из-за разрыва контекста. Пользователь пришёл по одной ссылке, а конверсия ушла без тех же параметров, или Keitaro принял дубликат, и отчёты разъехались.

Разберём типовые места, где теряется смысл.

Сохраните click context на стороне конверсии

Самый частый провал: лендинг отправляет конверсию в Keitaro, но не отправляет вместе с ней идентификатор клика или subid.

Чтобы этого избежать, выберите один из рабочих контуров:

• хранить идентификатор в cookie, который устанавливает редирект Keitaro
• передавать идентификатор в скрытое поле формы/в URL параметрах до момента отправки
• использовать endpoint Keitaro, который связывает конверсию с кликом по параметру, который вы получаете при редиректе

Какой бы метод вы ни выбрали, проверьте сценарий «закрыли вкладку и открыли снова» и сценарий «конверсия через несколько часов». Если контекст исчезает из-за cookie lifetime, вы увидите это в виде “вроде конверсия пришла, но UTM пустые”.

Проверьте окна атрибуции и обработку отложенных конверсий

Отложенные конверсии — обычная история: пользователь кликнул, ушёл думать, вернулся позже.

Тогда важно, чтобы:

• трекер мог связать конверсию с кликом в пределах выбранного окна атрибуции
• внешний endpoint получал один и тот же набор идентификаторов, иначе отчёт может раздвоиться

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

Контроль дублей: идемпотентность конверсий

Дубли возникают из-за того, что:

• пользователь отправляет форму повторно
• лендинг делает повторный запрос при медленной сети
• ваш backend повторно вызывает webhook при таймауте

Решение — идемпотентность. Вы должны иметь ключ, по которому конверсия учитывается один раз. Обычно это transactionid/orderid. Когда он есть, вы можете хранить соответствие и пропускать повторные события.

Если orderid появляется не сразу (например, платёжный провайдер подтверждает позднее), контролируйте дубль на уровне статуса. То есть один и тот же orderid может сначала прийти как “pending”, а затем как “paid”. В этом случае важна логика обновлений, а не просто “принять один раз”.

Порядок в цепочке: что будет «истиной»

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

Чтобы избежать конфликтов:

• определите, кто главный источник статуса (чаще всего вы в CRM фиксируете итоговый paid/failed)
• используйте этот статус для final postback в аналититику
• если вы отправляете промежуточные события (lead/pending), отдельно маркируйте их в параметрах

Тогда даже если промежуточные события приходят в разное время, финальная картинка будет собрана корректно.

Практический пример связки: от клика до конверсии в аналитике и атрибуции

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

Шаг 1. Рекламный URL ведёт на трекер с UTМ и subid

Допустим, вы настраиваете рекламу так, чтобы в ссылке были:

• utm_source=google
• utm_medium=cpc
• utmcampaign=springoffer_A
• subid=publisher_12
• gclid (если есть)

Вы отправляете пользователя на URL трекера вида:

• https://tracker.example.com/route?utmsource=…&utmmedium=…&utm_campaign=…&subid=…

Keitaro при клике сохраняет эти параметры и формирует редирект на лендинг.

Шаг 2. Редирект на лендинг сохраняет контекст для конверсии

После редиректа лендинг получает контекст. Здесь возможны варианты:

• Keitaro устанавливает cookie при редиректе
• или лендинг получает скрытый параметр и возвращает его при отправке формы

Цель одна: когда пользователь дойдёт до thank-you page или отправит форму, Keitaro должен получить те же значения utm_* и subid.

Шаг 3. На стороне конверсии отправляется событие в Keitaro

На лендинге вы размещаете обработчик, который вызывает Keitaro goal. Обычно это либо готовый JS/пиксель, либо серверный endpoint.

В конверсионном запросе важно передать:

• идентификатор заказа/лида (orderid/leadid), если он у вас есть
• value/revenue, если знаете сумму заранее
• статусы (например, paid/complete)

Шаг 4. Keitaro делает postback в аналитику и CRM

Как только Keitaro подтверждает событие, он отправляет postback во внешнюю систему.

Например, в CRM вы можете отправлять событие lead/order. В аналитику вы можете отправлять то же событие как purchase/lead с параметрами кампании.

Проверка на этом шаге проходит через два канала:

• лог Keitaro: видите, что postback был отправлен, и какой ответ пришёл
• лог/веб-интерфейс внешней системы: видите, что событие появилось с нужными параметрами

Шаг 5. Атрибуция становится проверяемой

После первых тестовых прогонов у вас появляется возможность проверить «склейку» по цепочке. Вы берёте один test order_id и смотрите:

• какие параметры были в клике
• какие параметры ушли в Keitaro при конверсии
• какие параметры пришли в аналитику/CRM

Если где-то UTМ или subid пустые, вы увидите это сразу и сможете исправить контур контекста.

Типичные ошибки при установке и интеграции Keitaro на VPS

Разберём частые причины, почему система «на вид работает», но в отчётах есть проблемы.

1) Домены и редиректы: проблема с Host и протоколом

Симптомы:

• ссылки из интерфейса трекера ведут не туда
• cookies выставляются не на тот домен
• трекер считает, что вы на HTTP, хотя на самом деле в браузере HTTPS

Что делать:

• проверить конфиги reverse proxy
• убедиться, что передаются X-Forwarded-Proto и Host
• проверить cookie domain и secure flags

2) Разрыв контекста между кликом и конверсией

Симптомы:

• в Keitaro конверсии есть, но utm_campaign пустой
• аналитика принимает события, но распределение по кампаниям «пустое»

Что делать:

• проверить, есть ли в запросе конверсии те же subid/utm_*
• проверить cookie lifetime и путь (path)
• проверить сценарий с задержкой конверсии

3) Дубли конверсий

Симптомы:

• конверсий больше, чем реальных оплат
• вы видите несколько postback на один и тот же заказ

Что делать:

• ввести идемпотентный ключ: orderid/transactionid
• контролировать повторные запросы на уровне лендинга и на уровне обработчиков
• логировать входящие postback и сравнивать keys

4) Неправильные настройки времени и часового пояса

Симптомы:

• в аналитике даты конверсий «плавают»
• отчёты по дням не совпадают с логами Keitaro

Что делать:

• выставить timezone на VPS
• проверить timezone внутри контейнеров
• использовать единый источник времени при формировании параметров postback

5) Внешний endpoint не отвечает или режет запросы

Симптомы:

• в логах Keitaro постбеки с ошибками
• внешняя система не показывает события

Что делать:

• проверить firewall/VPS egress
• проверить доступность endpoint из VPS
• убедиться, что метод (GET/POST), заголовки и формат payload соответствуют ожиданию

6) Перепутаны переменные при формировании postback

Симптомы:

• utmsource приходит как utmcampaign
• значения subid не совпадают с ожиданиями

Что делать:

• сделать тестовый постбек в «песочницу» (endpoint, который просто пишет входящие параметры)
• после успешного формата подключать реальный endpoint аналитики

Эксплуатация: мониторинг, бэкапы, масштабирование

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

Мониторинг и логирование: минимум, без которого нельзя

Поставьте себе правило: в каждый момент вы должны отвечать на два вопроса.

• Сколько кликов/конверсий приходит и не падает ли поток?
• Успешны ли postback в внешние системы?

Для этого полезны:

• логи Keitaro по кликам и конверсиям
• логи отправок постбеков: URL, статус ответа, latency
• логи reverse proxy: ошибки 4xx/5xx и причины

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

Бэкапы: что бэкапить в первую очередь

Бэкап нужен не только БД. В реальности ломается чаще конфиг и правила, чем сами данные.

Обычно бэкапят:

• БД Keitaro (данные кампаний, правил, кликов/конверсий)
• конфиги контейнеров/тома (если они не в коде)
• файлы, где лежат настройки источников/трекинг-скриптов (если они не берутся из интерфейса)

Минимальный подход: регулярно делать snapshot томов и БД, плюс хранить историю в течение нескольких дней, а конфиги — отдельно.

Обновления: как делать без сюрпризов

Обновлять лучше по плану:

1. Сначала на тестовом окружении (хотя бы отдельный VPS или отдельный контейнер)
2. Потом в production в окно с минимальным трафиком
3. После обновления прогнать контрольный набор ссылок и тестовых конверсий

Не пытайтесь «сразу и всё»: обновление в середине активной кампании без проверок почти гарантирует лишние часы на отладку.

Масштабирование: когда оно понадобится

Масштабирование обычно требуется, если:

• вы растите по кликам и нагрузка на БД/приложение начинает расти
• правила редиректа стали тяжёлыми
• внешние постбеки начинают задерживаться

Чаще всего помогает улучшение инфраструктуры (ресурсы VPS, быстрая дисковая подсистема). Разделять на несколько инстансов логически возможно, но это уже отдельный дизайн под вашу архитектуру данных и атрибуции.

Чеклист перед запуском связки Keitaro с аналитикой

• Домен трекера резолвится в VPS, сертификат HTTPS выдан и корректен
• Редиректы по тестовым URL работают и не теряют UTМ/subid
• Cookie/контекст, который нужен для конверсии, сохраняется до момента события
• Goal в Keitaro корректно принимает конверсию (и дубликаты не создают лишние записи)
• Postback в аналитику отправляется при конверсии и внешний endpoint отвечает успешно
• В аналитике события появляются в нужной витрине/цели, а параметры (utm_campaign, subid) заполнены
• Таймзоны выровнены: даты и часы совпадают с логами трекера
• Есть базовые логи для расследования: клики, конверсии, postback-ответы
• Настроены бэкапы БД и томов, проверено восстановление на тестовом стенде

Итог: план действий на ближайшие 2–3 часа

Если вы хотите сделать развертывание Keitaro на VPS и связку с аналитикой и атрибуцией максимально безболезненно, действуйте так.

1. Поднимите Keitaro на VPS через контейнерную схему, включите HTTPS и проверьте редирект по одной тестовой ссылке.
2. Настройте контур клика и убедитесь, что UTМ и subid сохраняются до конверсии.
3. Подключите один goal и один внешний endpoint (лучше в песочницу или на тестовую цель), отправьте тестовую конверсию и проверьте параметры.
4. Только после того, как атрибуция «сшилась» (есть и конверсия, и нужные UTМ), расширяйте интеграцию на остальные события, суммы и статусы.
5. Закрепите это мониторингом и минимальными бэкапами, чтобы следующий запуск не превращался в разбор “что сломалось”.

Когда контекст клика и конверсии совпадает, Keitaro становится удобной точкой правды для атрибуции. А внешняя аналитика перестаёт быть «витриной на глазок» и начинает отражать вашу реальную цепочку: от клика на рекламе до события в отчётах.