Как отслеживать источники и оплаты Telegram-бота на aiogram 3

1. Подключите SDK

python -m pip install "metricway-sdk[aiogram]"

Нужен Python 3.10 или новее. Создайте проект, сохраните токен в METRICWAY_PROJECT_TOKEN и подключите MetricsClient и setup_aiogram_metrics по полному примеру запуска.

Вызовите metrics.start() при запуске и metrics.close() при остановке. Middleware автоматически собирает сообщения, callback-запросы, ошибки и источники из /start. Платежи передавайте отдельно.

2. Создайте отдельную ссылку для источника

https://t.me/YOUR_BOT_USERNAME?start=partner_a

Замените имя бота. Для другого размещения используйте другую метку, например article_aiogram. При запуске по ссылке пользователь отправляет /start partner_a; middleware записывает start payload.

Текущий middleware SDK передаёт start_payload, а отчёт источников группирует по utm_source. Чтобы метка стала названием источника, в полном примере запуска замените создание MetricsClient следующим фрагментом. Это небольшой адаптер поверх публичного метода SDK:

import os
from metricway import MetricsClient

class SourceMetricsClient(MetricsClient):
    def track_traffic(self, user_id, start_payload="", utm_source="",
                      utm_campaign="", referrer=""):
        super().track_traffic(
            user_id=user_id, start_payload=start_payload,
            utm_source=utm_source or start_payload,
            utm_campaign=utm_campaign, referrer=referrer,
        )

metrics = SourceMetricsClient(
    api_url="https://metricway.tech",
    project_token=os.environ["METRICWAY_PROJECT_TOKEN"],
)

Передайте этот же metrics в setup_aiogram_metrics, запустите и закройте клиент по полной инструкции. Автоматический вызов middleware заполнит источник из метки, например partner_a. Не отправляйте вторую запись трафика для того же запуска. Если источник передаётся вручную, SDK также принимает utm_source и utm_campaign.

UTM-метки ссылки на сайт metricway и start payload ссылки на ваш бот решают разные задачи: первая измеряет продвижение сервиса аналитики, вторая — привлечение пользователей вашего бота.

3. Отправьте подтверждённую покупку

# Вызывайте после проверки успешной оплаты на стороне сервера.
# Для внешнего провайдера используйте проверенный webhook.
metrics.track_purchase(
    user_id=buyer_telegram_id,
    amount=paid_amount_rub,
    currency="RUB",
    product_id="subscription_month",
    payment_provider="your_payment_provider",
)

Переменные в примере — уже проверенные данные вашей платёжной интеграции. Передайте тот же Telegram ID, который использовался для источника. Сумма должна быть в рублях, а не в копейках; автоматической конвертации валюты нет.

Не отправляйте покупку при нажатии кнопки оплаты. Защитите обработку уведомления провайдера от повторного учёта одного платежа: повторная доставка webhook не является новой покупкой.

Для месячной подписки укажите в кабинете месячный тип продукта subscription_month. Классификация требуется для подписочных метрик.

4. Проверьте весь путь на тестовом проекте

1. Запустите бота по ссылке с меткой и проверьте поступление события и источника.
2. Используйте тестовый режим платёжного провайдера и проверьте одну подтверждённую покупку.
3. Сопоставьте Telegram ID в источнике и покупке; убедитесь, что платеж записан один раз.
4. Повторно доставьте то же тестовое уведомление: новая покупка появляться не должна.
5. Откройте одинаковый период в финансовом отчёте и таблице источников.

В реальном проекте используйте существующие подтверждённые покупки. Тестовые оплаты не отправляйте в рабочую аналитику.

5. Прочитайте результат

• Привлечённые пользователи: есть ли события с нужной меткой?
• Покупатели: удалось ли связать источник с оплатой?
• Конверсия: какая доля привлечённых пользователей покупает в выбранном периоде?
• Повторные покупки: есть ли у пользователя больше одной покупки в доступной истории?

Без реальных рекламных расходов CAC не помогает оценить окупаемость. При неполной истории нельзя надёжно определить, была ли покупка первой за всё время жизни бота.

SDK автоматически передаёт текст сообщений, callback data и стеки ошибок. Перед подключением проверьте их содержимое. Очередь хранится в памяти, поэтому при сбоях возможна потеря событий.

Документация и следующий шаг

Документация опубликованного SDK · Полный пример aiogram · Аналитика подписочных ботов

Free: один проект, до 10 000 событий в месяц и 30 дней истории.