Обзор
Рекламные кампании используют механизм Telegram Deep Links для привязки новых пользователей к источникам трафика. Каждая кампания генерирует уникальную ссылку вида:
https://t.me/{bot_username}?start={start_parameter}
Типы бонусов
| Тип | Описание |
|---|
| balance | Начисление на баланс (в копейках) |
| subscription | Триальная подписка с настраиваемыми параметрами |
| tariff | Полноценная подписка по конкретному тарифу |
| none | Только отслеживание (без бонуса) |
Balance (баланс)
Фиксированная сумма начисляется на баланс пользователя. Пользователь видит сообщение: “Вы получили за регистрацию по кампании ''!”
Subscription (триальная подписка)
Создаёт триальную подписку с параметрами:
| Параметр | Описание |
|---|
subscription_duration_days | Длительность (1-730 дней) |
subscription_traffic_gb | Трафик в ГБ (0 = безлимит) |
subscription_device_limit | Лимит устройств |
subscription_squads | Список серверов (UUID). Если пусто — случайный триальный сервер |
Подписка не создаётся, если у пользователя уже есть активная подписка.
Tariff (тарифная подписка)
Создаёт полноценную (не триальную) подписку по выбранному тарифу:
tariff_id — ссылка на активный тарифtariff_duration_days — длительность (1-730 дней)- Трафик, устройства и серверы наследуются из тарифа
None (только отслеживание)
Бонус не выдаётся, но регистрация привязывается к кампании для аналитики.
Механизм Deep Link
Как работает
- Генерация ссылки — каждая кампания имеет уникальный
start_parameter (3-32 символа, [A-Za-z0-9_-])
- Пользователь переходит по ссылке
/start {parameter}
- Обработка в боте:
- Ищет кампанию по
start_parameter
- Если найдена — сохраняет
campaign_id в FSM
- Если у кампании есть партнёр — устанавливает его как реферера
- Если кампания не найдена — трактует параметр как реферальный код
- Бонус применяется после завершения регистрации
Сохранение через проверку канала
Если включена обязательная подписка на канал (CHANNEL_IS_REQUIRED_SUB=true), параметр кампании сохраняется в Redis и восстанавливается после подписки.
Веб-ссылка для MiniApp
Дополнительный формат: {MINIAPP_CUSTOM_URL}/?campaign={start_parameter}
Ограничения
- Только для новых пользователей — существующие видят “Эта ссылка доступна только для новых пользователей”
- Один бонус на пользователя — уникальность по
(campaign_id, user_id)
- Подавление welcome-оффера — при регистрации через кампанию стандартный триал/welcome-оффер пропускается
- Самореферирование — партнёр не может получить бонус по своей кампании
Партнёрская интеграция
Кампании можно привязать к партнёру (partner_user_id):
- При создании/редактировании выбирается из одобренных партнёров (
partner_status='approved')
- Переход по партнёрской кампании автоматически делает партнёра реферером нового пользователя
- Все реферальные доходы от пользователей кампании отмечаются
campaign_id в таблице referral_earnings
Аналитика
Метрики по кампании
| Метрика | Описание |
|---|
registrations | Всего зарегистрировано |
balance_issued | Всего начислено на баланс |
subscription_issued | Количество выданных подписок |
total_revenue_kopeks | Доход от пользователей кампании |
conversion_rate | Конверсия в оплату (%) |
trial_conversion_rate | Конверсия триала в оплату (%) |
avg_revenue_per_user_kopeks | Средний доход на пользователя |
avg_first_payment_kopeks | Средний первый платёж |
Общая статистика
- Всего / активных / неактивных кампаний
- Суммарные регистрации
- Суммарные начисления баланса и подписок
Управление (админ-панель)
Создание кампании (пошагово)
- Название (3-100 символов)
- Start параметр (3-32 символа,
[A-Za-z0-9_-], уникальный)
- Тип бонуса (4 варианта через инлайн-клавиатуру)
- В зависимости от типа:
- Balance: сумма в рублях
- Subscription: дни, трафик, устройства, серверы
- Tariff: выбор тарифа, длительность
- None: сразу создаётся
Действия
| Действие | Описание |
|---|
| Статистика | Детальные метрики кампании |
| Включить/Выключить | Переключение is_active |
| Редактирование | Название, start параметр, параметры бонуса |
| Удаление | С подтверждением (заблокировано, если есть регистрации) |
| Фильтр пользователей | Просмотр пользователей, пришедших через кампанию |
Уведомления
При переходе по ссылке кампании администратор получает уведомление с:
- Названием кампании и ID
- Информацией о пользователе
- Статусом (новый / уже зарегистрирован)
- Деталями бонуса
Cabinet и Web API
Cabinet Admin API
Полный CRUD: создание, просмотр, редактирование, удаление, переключение статуса. Дополнительно:
- Обзорная статистика (
GET /overview)
- Детальная статистика (
GET /{id}/stats)
- Список зарегистрированных пользователей (
GET /{id}/registrations)
- Доступные серверы, тарифы и партнёры для настройки
Web API
CRUD через API-токен: POST, GET, PATCH, DELETE.
Связанные переменные
Специальных переменных нет. Поведение зависит от:
| Переменная | Описание |
|---|
DEFAULT_DEVICE_LIMIT | Лимит устройств по умолчанию для subscription-бонуса |
MAX_DEVICES_LIMIT | Максимальный лимит устройств |
MINIAPP_CUSTOM_URL | Базовый URL для веб-ссылок кампаний |
BOT_USERNAME | Для генерации deep link (автоопределяется) |
