Как тестировать и отлаживать Telegram Mini App

Коротко

Mini App — это веб-страница внутри WebView Telegram. Отладка сводится к четырём привычкам:

1. Запускайте приложение локально и открывайте его через HTTPS-туннель.
2. Подключайте к этому адресу отдельного dev-бота, чтобы реальные пользователи не видели недоделки.
3. Для повседневной работы над интерфейсом мокайте окружение Telegram в обычном браузере.
4. Перед релизом открывайте приложение во всех клиентах с включёнными devtools WebView.

Локальный запуск через HTTPS-туннель

Telegram открывает Mini App по HTTPS, поэтому просто localhost внутри приложения не заработает.

1. Запустите dev-сервер, например на порту 5173.
2. Поднимите туннель: cloudflared tunnel --url http://localhost:5173 или ngrok http 5173.
3. В @BotFather укажите адрес туннеля для Mini App или кнопки меню вашего dev-бота.
4. Откройте бота в Telegram и запустите приложение.

Типичные проблемы:

• Некоторые dev-серверы, в том числе Vite, отклоняют запросы с незнакомых хостов. Добавьте домен туннеля в разрешённые хосты.
• Горячей перезагрузке может понадобиться настройка WebSocket, чтобы она работала через туннель.
• Бесплатные туннели часто меняют адрес при каждом перезапуске, и его приходится обновлять в BotFather. Зарезервированный домен избавляет от этого шага.

Тестовое окружение Telegram

У Telegram есть отдельный тестовый сервер со своими аккаунтами, ботами и данными. Он полезен, когда нужна полная изоляция, например чтобы проверить платежи, не трогая продакшен.

• iOS: нажмите на иконку настроек 10 раз, откройте Accounts, выберите Login to another account, затем Test.
• Telegram Desktop: откройте настройки, зажмите Shift + Alt и кликните правой кнопкой по Add Account, затем выберите Test Server.
• Создайте бота через @BotFather внутри тестового окружения. Запросы к Bot API тогда идут на https://api.telegram.org/bot<token>/test/METHOD.
• В тестовом окружении разрешены ссылки на Mini App без TLS, что упрощает локальную работу.

Для большинства проектов хватает dev-бота в обычном окружении; тестовый сервер — дополнительный слой, а не обязательное требование.

Включение отладки WebView

Названия пунктов меню могут меняться между версиями клиентов — актуальные шаги есть в официальной документации Mini Apps. Как запасной вариант подойдёт консоль внутри страницы, например Eruda, подключаемая только в dev-сборках: она показывает логи прямо на телефоне.

Моки initData и параметров темы

В обычном браузере у window.Telegram.WebApp нет initData, пользователя и темы. Мокайте их только в разработке:

const tg = (window as any).Telegram?.WebApp;

if (import.meta.env.DEV && !tg?.initData) {
  const theme = {
    bg_color: "#ffffff",
    text_color: "#000000",
    button_color: "#2481cc",
    button_text_color: "#ffffff",
  };
  for (const [key, value] of Object.entries(theme)) {
    document.documentElement.style.setProperty(
      `--tg-theme-${key.replace(/_/g, "-")}`,
      value,
    );
  }
}

Библиотеки вроде @telegram-apps/sdk предлагают хелперы, которые мокают всё окружение запуска, включая пользователя и стартовые параметры.

Сложнее с бэкендом: он проверяет initData по HMAC-подписи на основе токена бота. Два безопасных варианта: подписывать тестовую initData самостоятельно токеном dev-бота в тестах или добавить обход только для разработки с фиксированным тестовым пользователем, который невозможно включить в продакшене.

Держите и мок тёмной темы: многие баги вёрстки проявляются только при смене цветов.

Проверка поведения в разных клиентах

• Viewport: видимая высота меняется при открытии клавиатуры — проверьте формы внизу экрана.
• Безопасные зоны и полноэкранный режим на телефонах с вырезом.
• MainButton и BackButton: видимость, текст и обработчики на каждом экране.
• Смена темы при открытом приложении через событие themeChanged.
• Ссылки: внешние страницы через openLink, ссылки Telegram через openTelegramLink.
• Старые клиенты: оборачивайте новые методы в проверку isVersionAtLeast.
• Android, iOS, Desktop, macOS и Telegram Web — на маленьком экране и медленной сети.