При разработке экосистемы Telegram многие разработчики сталкиваются с общей проблемой: как одновременно управлять двумя наборами кода для бота и мини-приложения? Традиционный подход заключается в раздельном развертывании двух проектов, что не только увеличивает затраты на обслуживание, но и может привести к проблемам с синхронизацией данных и платежными процессами.
В этой статье мы представим совершенно новый подход к разработке: использование одного проекта Next.js для одновременной реализации Telegram Bot и Mini App, достигая истинного единого кода, единого развертывания, бесшовной интеграции. Вы научитесь создавать полноценную систему игровых очков, включая ежедневные бонусы за вход, реальные платежи через Telegram Stars и функции мгновенных уведомлений.
В традиционном режиме разработчикам необходимо:
С унифицированным решением Next.js вы можете:
Этот подход особенно подходит для быстрой проверки идей, разработки MVP-продуктов или для независимых разработчиков, желающих быстро запустить проект.
Мы создадим систему игровых очков, которая будет обладать следующими функциями:
/start, /help, для запуска мини-приложения в один клик.Вся система будет работать в одном приложении Next.js, обеспечивая полное бесшовное взаимодействие между ботом и мини-приложением.
Перед началом разработки вам понадобятся следующие инструменты:
ngrok config add-authtoken <ваш_токен> для привязки аккаунта.ngrok http 3000 из этой папки.Полный исходный код и подробную документацию можно найти в соответствующем Telegram-канале (ссылку можно найти в описании оригинального видео).
git clone <адрес_репозитория>
cd <директория_проекта>
npm install
В корневой папке проекта создайте файл .env.local для хранения конфиденциальной информации:
TELEGRAM_BOT_TOKEN=ваш_токен_бота
NEXT_PUBLIC_APP_URL=адрес_вашего_ngrok
Важное примечание: Убедитесь, что .env.local добавлен в .gitignore, чтобы избежать утечки токена бота.
/newbot для создания нового бота.bot)..env.local.# Терминал 1: Запуск Ngrok
ngrok http 3000
# Терминал 2: Запуск сервера разработки Next.js
npm run dev
# Терминал 3: Настройка Webhook
npm run webhook:setup
Если все настроено правильно, вы увидите сообщение "Webhook set successfully".
/mybots и выберите вашего бота.Теперь, когда пользователи откроют вашего бота, они увидят кнопку для запуска игры, нажав на которую, они перейдут в интерфейс мини-приложения!
Все обновления, отправляемые Telegram (команды пользователя, уведомления о платежах и т. д.), передаются через Webhook в маршрут /api/telegram/webhook.
Основные типы обрабатываемых сообщений включают:
/start, /help и т. д.При первом отправлении команды /start бот немедленно отправляет кнопку «Запустить игру», не требуя дополнительных инструкций.
Ключевым элементом функции оплаты является маршрут /api/buy-points:
createInvoiceLink).Ключевая конфигурация:
provider_token оставляем пустым (режим Telegram Stars).currency устанавливаем в XTR.prices указываются в количестве звезд (не в центах).Бонус для разработчиков: после каждой покупки возвращается идентификатор квитанции, который вы можете немедленно использовать для тестирования возврата средств с помощью команды /refund <ID_квитанции>, без необходимости ожидания подтверждения или ручной обработки. Это чрезвычайно эффективно для тестирования реального платежного процесса.
В маршруте /api/claim-daily реализован механизм поощрения, основанный на времени:
На фронтенде используется компонент таймера реального времени, который обновляется каждую секунду, информируя пользователя о том, когда он сможет получить следующий бонус. Этот шаблон может быть расширен для любых игровых механик, требующих ограничения по времени (например, восстановление энергии, охлаждение при розыгрыше и т. д.).
Хотя в этой демонстрации используется хранение в памяти, перед запуском реального проекта необходимо внести следующие изменения:
Рекомендуемые платформы для развертывания:
При развертывании не забудьте обновить URL Webhook и ссылку на кнопку меню Mini App на домен вашего продакшена.
Telegram требует использования протокола HTTPS для Webhook и Mini App, что localhost не может обеспечить. Ngrok создает общедоступный HTTPS-туннель, перенаправляя запросы на ваш локальный сервер разработки.
На этапе разработки вы можете купить небольшое количество Telegram Stars (от нескольких центов), а затем использовать команду /refund для мгновенного возврата средств. Это позволит протестировать платежный процесс, обратные вызовы Webhook и логику возврата средств в реальном режиме, не нуждаясь в повторных пополнениях.
Категорически нет. Хранение в памяти теряет все данные при перезагрузке сервера. Необходимо использовать постоянную базу данных (например, PostgreSQL) и иметь план резервного копирования и миграции.
Главное преимущество — повышение эффективности разработки и снижение затрат на обслуживание. Вам не придется:
Вся логика находится в одном проекте, повышая частоту повторного использования кода и ускоряя поиск ошибок.
Для MVP-продуктов и приложений среднего размера она вполне подходит. Если суточная аудитория достигает миллиона пользователей, рекомендуется разделить бэкенд бота и фронтенд мини-приложения, используя архитектуру микросервисов и специализированные очереди сообщений для обработки высоких нагрузок.
В ходе практической демонстрации в этой статье вы освоили ключевые навыки создания унифицированного приложения Telegram Bot + Mini App на Next.js. Такой подход к разработке поможет вам быстро проверять идеи, снижать затраты на разработку и заложить прочный фундамент для дальнейшего расширения. Приступайте к практике прямо сейчас и создайте свою собственную Telegram-игру за минимальное время!
Обзор
