Перейти к основному содержимому

Аналитика, источники и рекламный бюджет

Текущий интерфейс и границы MCP​

В интерфейсе ссылка создаётся сразу из бота и метки (https://t.me/<username>?start=raspred), без сохранения размещения. Необязательный бюджет записывается HTTP POST /api/projects/{id}/analytics/acquisition/budgets. Отдельного MCP-инструмента для этой атомарной операции пока нет; не придумывайте db_create_analytics_budget. Контракт и ограничения: руководство API.

В UI используется термин «Источник», однако совместимые MCP-инструменты сохраняют технические сущности размещения и расхода. Поэтому последовательность ниже нужна для расширенной регистрации через MCP, а не для простого получения ссылки в интерфейсе.

  1. Получите настоящие project_id и token_id через db_list_projects и db_list_bot_tokens.
  2. Вызовите db_get_analytics_v2 с одним периодом. Сохраните as_of, revision, coverage; неполное покрытие не означает нулевую аудиторию.
  3. Проверьте db_list_analytics_sources; если нужно, создайте источник через db_create_analytics_source.
  4. Проверьте существующие связи через db_list_analytics_placements. Для новой зарегистрированной публикации используйте db_create_analytics_placement с источником, ботом, датой начала и поясом.
  5. Вызовите db_create_analytics_link и используйте возвращённый URL с зарегистрированной bc_-меткой. Это расширенный API, не локальный конструктор произвольной метки. При HTTP 409 объясните конфликт маршрута; не меняйте сценарий скрытно.
  6. Сохраните рекламный бюджет через db_create_analytics_expense: amount строкой, RUB либо USD и календарный day. Несколько дней распределяйте через allocation=equal и untilDay только после согласованного предпросмотра. Повторное создание добавляет ещё одну запись, не заменяет старую.
  7. Вызовите db_get_acquisition_report с календарными границами либо без них за весь срок. includeSources="true" включает обнаруженные источники без финансовых записей. Считайте результаты на сервере; null не заменяйте нулём.
  8. Исправления — db_update_analytics_*, история — db_get_analytics_history. Архивирование сохраняет прошлые результаты.

В рекламном отчёте returningUsers — люди, использовавшие бота до начала выбранного окна и снова вошедшие в нём по ссылке/start. Просто написанное сообщение относится к активности снимка, но не является возвратом по рекламе. Повторный вход нового для этого окна человека не делает его вернувшимся. Первый источник не переписывается. Люди могут вернуться по нескольким источникам; не суммируйте строки как уникальных людей проекта.

Одна обычная метка у одного бота объединяет публикации. Повторный бюджет не переносит прежнюю дату начала. Новая дата оплаты не позволяет отличить новую публикацию от старой с той же ссылкой. Для раздельного учёта выбирайте другую метку. Авторизационные link_, а также ref/ref_* запрещены в HTTP бюджете; реферал подтверждается только зарегистрированной связью.

db_get_analytics_v2 использует token_id; формы создания и отчёт сохраняют имена HTTP API внутри data/фильтров (tokenId, placementId, sourceId). Точные схемы доступны через MCP tools/list и get_tool_docs.

В снимке различайте new_users и restored_users: второе число показывает людей с первым сохранённым действием в окне, но неизвестным настоящим началом использования. Оно доступно в current/previous.audience и points[], не добавляется к новым пользователям или знаменателю цены привлечения. audience.first_history_status показывает полноту окна; при восстановленной истории это partial. unknown_first_users относится ко всей аудитории, а не только окну. Люди проекта дедуплицируются между ботами.

В sources[] и source_points[] категории new_users и restored_users также разделены. Их сумма описывает первые сохранённые взаимодействия, не точное рекламное привлечение. Источник старого /start связывается с первым взаимодействием только при совпадении физического Telegram-сообщения в той же области проекта и бота; текущая метка профиля и близкое время не заменяют это подтверждение. Поздние /start учитываются как повторные входы, не переписывая первый источник. Восстановленная метка не даёт оснований включать restored_users в CPA или назначать пригласившего по одному лишь ref_*.

Параметры авторизации link_ исключены из наблюдаемых меток и выдачи источников; не пытайтесь получать исходный секрет через историю, журналы или MCP. Наблюдаемая метка сама по себе не подтверждает зарегистрированное размещение. Подробная методика — в руководстве API аналитики.

Пример снимка:

{"tool":"db_get_analytics_v2","arguments":{"project_id":12,"period":"7d","comparison":"previous","timezone":"Europe/Moscow"}}

Пример оплаты:

{"tool":"db_create_analytics_expense","arguments":{"project_id":12,"data":{"placementId":6,"day":"2026-11-01","amount":"3000.00","currency":"RUB"}}}

3 000 ₽ и 200 подтверждённых новых пользователей за совпадающее окно дают 15 ₽. Данные о простых сообщениях в группе не становятся привлечёнными пользователями. ref_* без зарегистрированной связи не подтверждает реферера; link_* не доказывает рекламный источник. Коды входа и тексты переписки не запрашиваются и не возвращаются аналитикой.

MCP передаёт тот же авторизованный HTTP API и сохраняет его decimal-строки, null, время снимка и ограничения истории. Чужие ID отклоняются. Для временного отказа получите новый ответ позже; не выдавайте старый снимок за актуальный. Уведомление WebSocket сообщает об изменении версии, окончательные значения берутся из нового снимка.

costPerUserByCurrency.RUB/USD показывает отдельную цену в исходных валютах; при отсутствии курса она может быть доступна, когда общий пересчитанный costPerUser=null. null в исходной валюте означает отсутствие подходящего расхода, новых пользователей или достаточной истории/полного дня.

Если первое подтверждённое событие человека — настоящий callback кнопки в группе или супергруппе, отчёт источников показывает «Группа · название». Стабильный ID имеет вид group:<token_id>:<chat_id>; переименование меняет только подпись. При отсутствии названия используется ID чата. Название берётся только из той же области проекта и бота. Обычная переписка и более поздние нажатия не меняют первый источник; проектный отчёт по-прежнему выбирает самое раннее взаимодействие человека среди ботов. Это место первого взаимодействия, а не подтверждённое рекламное размещение: source_id, расходы и CPA не изменяются. Аудированные исторические нажатия также могут определить группу первого контакта, если известен ID чата, без объявления физического callback.

Рейтинг групп по взаимодействию сортируется по уникальным людям, имевшим направленный контакт в группе за период, включая аудированные исторические свидетельства. Один человек в нескольких записях или у нескольких ботов проекта считается в этой группе один раз. В API leaders.groups[].people содержит число людей; total, messages, callbacks сохраняют прежний смысл физических действий. Старые свидетельства их не увеличивают. Наблюдаемая переписка остаётся отдельным режимом. Уже перенесённая история используется автоматически без повторного создания событий или изменения расходов.

В разделе популярных кнопок доступны режимы «Нажатия» и «Люди». buttons[].people объединяет реальные callback и аудированные исторические свидетельства по человеку и подписи кнопки; повторные записи не увеличивают число людей. buttons[].count сохраняет точное число физических callback. Миграция 0034 переносит только безопасную подпись кнопки в независимую историю; очистка переписки её не удаляет. Callback payload и параметры link_ не переносятся. При отсутствии подписи используется «Кнопка без названия». Подписи объединяются по тексту, поэтому одинаковый текст в разных нодах не разделяется.

По принятой пользователем методике каждая аудированная старая запись кнопки считается нажатием. В режиме «Нажатия» интерфейс показывает сумму buttons[].count и buttons[].historical_count; режим «Люди» использует people. В подробностях составляющие разделены: с Telegram ID и из старой истории. Старые записи не переименовываются в физические callback и не меняют существующий контракт count. API возвращает до 100 подписей по числу нажатий, интерфейс показывает первые 20 по выбранному показателю. Новая миграция не нужна: применённая 0034 уже сохраняет необходимые подписи.

Карточка «Группы по сообщениям» отдельно ранжирует группы по числу наблюдаемых входящих сообщений за общий период (leaders.groups_messages). Она не зависит от режима соседнего рейтинга людей. В подробностях доступны число сообщений, уникальные авторы и переход в переписку группы. Callback и исходящие ответы бота не включены. Топ считается на сервере по сообщениям, а не пересортировкой усечённого топа по людям.

Размещение может быть явно связано с исторической меткой через analytics_placement_history_v2 (миграция 0035). Первые сохранённые обращения возвращаются отдельно как historicalUsers, не увеличивая newUsers и не меняя первоначальную атрибуцию. Повторные входы по метке учитываются в возвратах и повторных запусках. Для демонстрационной связи isDemo=true допускается demoCostPerContact — условная цена исторического контакта, только за полные календарные дни или весь срок. Она не является точной CPA. В интерфейсе видны отметки «Из истории» и «демо». Токены авторизации в привязку не допускаются.

Таблица источников в интерфейсе автоматически включает найденные источники без размещений. HTTP/MCP: includeSources="true" добавляет такие строки; без параметра прежний контракт размещений сохраняется. У автоматической строки placementId=null, rowKey — стабильный ключ, sourceKey — ключ источника; sourceId может отсутствовать (null) у исторической метки или статуса, tokenId=null означает весь проект. Расход отсутствует (null), а не равен нулю. Источники, уже связанные с размещениями или историческими метками, второй строкой не дублируются. Открытие таблицы не создаёт размещений и финансовых записей. Весь найденный список виден и при отсутствии контактов в выбранном окне.

Для бесплатного официального курса вызовите db_get_analytics_exchange_rate с project_id и day. Затем передайте rubPerUsd как exchangeRateRubPerUsd, а effectiveDay как exchangeRateDate в создание или обновление оплаты. Получение курса не изменяет существующие расходы. При HTTP 503 используйте ручной курс после уточнения пользователя; не подставляйте произвольное число.