> ## Documentation Index > Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt > Use this file to discover all available pages before exploring further. # Рекламные кампании > Deeplink-кампании с бонусами, аналитикой и партнёрской интеграцией ## Обзор Рекламные кампании используют механизм 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). Если пусто — случайный триальный сервер | > [!WARNING] > > Подписка не создаётся, если у пользователя уже есть активная подписка. ### Tariff (тарифная подписка) Создаёт полноценную (не триальную) подписку по выбранному тарифу: * `tariff_id` — ссылка на активный тариф * `tariff_duration_days` — длительность (1-730 дней) * Трафик, устройства и серверы наследуются из тарифа ### None (только отслеживание) Бонус не выдаётся, но регистрация привязывается к кампании для аналитики. ## Механизм Deep Link ### Как работает 1. **Генерация ссылки** — каждая кампания имеет уникальный `start_parameter` (3-32 символа, `[A-Za-z0-9_-]`) 2. **Пользователь переходит** по ссылке `/start {parameter}` 3. **Обработка в боте**: * Ищет кампанию по `start_parameter` * Если найдена — сохраняет `campaign_id` в FSM * Если у кампании есть партнёр — устанавливает его как реферера * Если кампания не найдена — трактует параметр как реферальный код 4. **Бонус применяется** после завершения регистрации ### Сохранение через проверку канала Если включена обязательная подписка на канал (`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` * На странице партнёра в Cabinet отображается статистика по каждой кампании: регистрации, рефералы, доход ## Аналитика ### Метрики по кампании | Метрика | Описание | | - | - | | `registrations` | Всего зарегистрировано | | `balance_issued` | Всего начислено на баланс | | `subscription_issued` | Количество выданных подписок | | `total_revenue_kopeks` | Доход от пользователей кампании | | `conversion_rate` | Конверсия в оплату (%) | | `trial_conversion_rate` | Конверсия триала в оплату (%) | | `avg_revenue_per_user_kopeks` | Средний доход на пользователя | | `avg_first_payment_kopeks` | Средний первый платёж | > [!NOTE] > > С `v4.1.0` в метрики кампании попадают и **гостевые покупки с лендингов**: слаг кампании сохраняется в покупке и учитывается наравне с регистрациями через deep link. См. [Лендинги](/cabinet/landings.md#привязка-к-рекламной-кампании). ### Графики и аналитика В Cabinet админ-панели доступна расширенная аналитика по каждой кампании: | Компонент | Описание | | - | - | | **Ежедневные тренды** | Area chart с регистрациями по дням | | **Период vs предыдущий** | Сравнение метрик текущего и прошлого периода с индикатором тренда | | **Топ регистрации** | Таблица самых результативных дней | | **Депозиты / траты** | Раздельные суммы пополнений и покупок пользователей кампании | ### Общая статистика * Всего / активных / неактивных кампаний * Суммарные регистрации * Суммарные начисления баланса и подписок ## Управление (админ-панель) ### Создание кампании (пошагово) 1. **Название** (3-100 символов) 2. **Start параметр** (3-32 символа, `[A-Za-z0-9_-]`, уникальный) 3. **Тип бонуса** (4 варианта через инлайн-клавиатуру) 4. В зависимости от типа: * Balance: сумма в рублях * Subscription: дни, трафик, устройства, серверы * Tariff: выбор тарифа, длительность * None: сразу создаётся ### Действия | Действие | Описание | | - | - | | **Статистика** | Детальные метрики кампании | | **Включить/Выключить** | Переключение `is_active` | | **Редактирование** | Название, start параметр, параметры бонуса | | **Удаление** | С подтверждением (заблокировано, если есть регистрации) | | **Фильтр пользователей** | Просмотр пользователей, пришедших через кампанию | ### Уведомления При переходе по ссылке кампании администратор получает уведомление с: * Названием кампании и ID * Информацией о пользователе * Статусом (новый / уже зарегистрирован) * Деталями бонуса ## Cabinet и Web API ### Cabinet Admin API Полный CRUD: создание, просмотр, редактирование, удаление, переключение статуса. Дополнительно: * Обзорная статистика (`GET /overview`) * Детальная статистика (`GET /{id}/stats`) * Данные для графиков (`GET /{id}/chart-data`) — ежедневные регистрации, тренды, период-vs-период, депозиты/траты * Список зарегистрированных пользователей (`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 (автоопределяется) | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.