Подключение аналитики к Telegram-боту за 10 минут

Установите SDK

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

Пакет опубликован на PyPI. Нужен Python 3.10 или новее.

Сохраните токен

METRICWAY_PROJECT_TOKEN=your-project-token
TELEGRAM_BOT_TOKEN=your-bot-token

Не помещайте настоящие токены в Git и не передавайте их в URL.

Подключите aiogram

import asyncio
import os

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message
from metricway import MetricsClient, setup_aiogram_metrics

metrics = MetricsClient(
    api_url="https://metricway.tech",
    project_token=os.environ["METRICWAY_PROJECT_TOKEN"],
)
dp = Dispatcher()
setup_aiogram_metrics(dp, metrics)

@dp.message(CommandStart())
async def start_command(message: Message) -> None:
    await message.answer("Привет!")

async def on_startup(bot: Bot) -> None:
    await metrics.start()

async def on_shutdown(bot: Bot) -> None:
    await metrics.close()

dp.startup.register(on_startup)
dp.shutdown.register(on_shutdown)

async def main() -> None:
    bot = Bot(token=os.environ["TELEGRAM_BOT_TOKEN"])
    try:
        await dp.start_polling(bot)
    finally:
        await bot.session.close()

if __name__ == "__main__":
    asyncio.run(main())

Вызовите setup_aiogram_metrics один раз при настройке роутера. start() запускает отправку, close() пытается отправить остаток при остановке.

Передайте оплату

metrics.track_purchase(
    user_id=message.from_user.id,
    amount=990,
    currency="RUB",
    product_id="pro_month",
    payment_provider="telegram_payments",
)

Используйте валюту, выбранную в проекте. Автоматической конвертации нет. Первую и повторные покупки metricway разделит автоматически.

Отследите trial

metrics.track_event(
    user_id=message.from_user.id,
    chat_id=message.chat.id,
    handler="trial_started",
    update_type="trial",
    payload={"product_id": "pro_month"},
)

Событие trial_started попадёт в системный шаг «Пробный период» продуктовой воронки.

Проверьте подключение

Отправьте боту /start test_campaign и вернитесь в кабинет. Статус станет зелёным не позднее чем через 30 секунд после первого принятого события. Если данных нет, проверьте токен, вызов start() и логи metricway.