Telegram Mini Apps (TMA) стали полноценной альтернативой мобильным приложениям. Они работают внутри мессенджера, имеют доступ к данным пользователя и позволяют создавать бесшовный UX. Однако при разработке на современных JS-фреймворках, таких как Vue 3, разработчики часто сталкиваются с неочевидными проблемами: «прыгающий» интерфейс при открытии клавиатуры, ограничения метода sendData и уязвимости при проверке авторизации на бэкенде.
В этой статье мы разберем, как правильно подключить Telegram WebApp JS к приложению на Vue 3, настроить стабильное отображение (viewport), обойти ограничения отправки данных и реализовать криптографически безопасную проверку initData на стороне PHP-сервера.
Шаг 1: Подключение Telegram WebApp JS в Vue 3
Официальная рекомендация Telegram — подключать скрипт SDK через CDN в секции <head> вашего index.html. Это гарантирует, что приложение всегда будет использовать актуальную версию API без необходимости постоянного обновления npm-зависимостей.
Для удобной и реактивной работы с SDK во Vue 3 лучше всего написать простой Composable. Он инкапсулирует глобальный объект window.Telegram.WebApp и предоставит удобный интерфейс для компонентов.
Шаг 2: Настройка темы и стабильного Viewport
Одна из главных проблем мобильных веб-приложений — изменение высоты экрана (viewport) при появлении экранной клавиатуры или скрытии системных плашек. В Telegram WebApp для этого предусмотрены параметры высоты.
Чтобы избежать резких скачков интерфейса, используйте CSS-переменные, которые динамически обновляются. Telegram автоматически передает параметры темы в CSS, но для позиционирования элементов (например, фиксированной кнопки «Оформить заказ» внизу экрана) лучше использовать событие viewportChanged.
В стилях CSS используйте созданную переменную вместо стандартных 100vh, которые некорректно обрабатываются в мобильных браузерах внутри WebView:
Шаг 3: Отправка данных боту и критическое ограничение sendData
Разработчики часто совершают ошибку, пытаясь использовать метод tg.sendData() для отправки результатов работы Mini App обратно в чат с ботом.
Важное ограничение API: Методtg.sendData()работает только в том случае, если Mini App был запущен через обычную кнопку клавиатуры (Keyboard Button). Если приложение запущено через Inline-кнопку в сообщении, кнопку в меню (Menu Button) или по прямой ссылке, вызовtg.sendData()завершится ошибкой или будет проигнорирован. Кроме того, этот метод мгновенно закрывает Mini App.
Если вам нужно передать данные без закрытия приложения или при запуске через Inline-кнопку, правильный паттерн выглядит так:
- Vue-приложение отправляет POST-запрос на ваш собственный бэкенд (API).
- В заголовках запроса передается строка авторизации
tg.initData. - Бэкенд валидирует эти данные, обрабатывает логику (например, создает заказ в БД).
- Бэкенд отправляет сообщение пользователю в Telegram от имени бота через стандартный Bot API (метод
sendMessage).
Если же вы используете Keyboard Button и вам действительно нужно вернуть простую строку и закрыть приложение:
Шаг 4: Безопасная валидация initData на PHP-сервере
Никогда не доверяйте данным, пришедшим из фронтенда (включая initDataUnsafe). Злоумышленник может легко подменить ID пользователя или баланс в объекте JS. Для проверки подлинности данных необходимо использовать строку Telegram.WebApp.initData, которая содержит хэш, подписанный токеном вашего бота.
При отправке запроса из Vue 3 передавайте initData в заголовке авторизации:
На стороне PHP-бэкенда мы должны распарсить эту строку, отсортировать параметры по алфавиту, создать проверочную строку и сравнить хэш с помощью HMAC-SHA256.
Этот метод гарантирует, что данные пользователя (ID, имя, username) не были изменены по пути, так как любой подлог нарушит хэш-сумму, создать которую без знания токена бота невозможно.
Резюме
Разработка Telegram Mini App на Vue 3 требует внимания к деталям мобильного UX и безопасности. Использование реактивных composables упрощает работу с SDK, правильная обработка событий viewport избавляет от «прыжков» интерфейса, а строгая криптографическая проверка initData на PHP гарантирует безопасность пользовательских данных и транзакций.
Если вам нужна помощь в проектировании архитектуры или разработке сложных Mini Apps, команда BotCreator поможет реализовать проект любой сложности.
