Перейти к содержанию
9 минут чтения
Тема: Практика Mini Apps · JavaScript · Диагностика

Telegram Mini App не открывается или показывает белый экран: что проверить

Для примера форма заявки открывается у разработчика в браузере, но в Telegram клиент видит белый экран или бесконечную загрузку. Пройдём путь от HTTPS-страницы до первого запроса к серверу. На каждом этапе важно определить, что уже загрузилось и где именно остановилось приложение.

Сначала уточняем, что именно не открывается

Разделите три ситуации: Telegram вообще не открывает окно, окно появляется без содержимого, интерфейс виден, но данные или вход не работают. У них разные причины. Запишите время, версию Telegram, платформу, способ запуска, адрес приложения без секретных параметров и версию вашей сборки.

Повторите запуск одним и тем же способом с тестового аккаунта. Для сравнения используйте ещё один клиент и другую сеть. Если ошибка есть только в одном окружении, это направление поиска, а не доказательство ошибки Telegram. Начните с собственного адреса, ресурсов и JavaScript.

Не просите пользователя прислать полный initData или ссылку с авторизационными данными. Для диагностики достаточно безопасного request ID и категории ошибки. Снимок экрана также может содержать личные сведения: обрежьте их до передачи в рабочий чат.

Проверяем адрес и HTTPS снаружи

Откройте точный URL приложения на устройстве пользователя в обычном браузере. Он должен возвращать нужную страницу без предупреждения сертификата, страницы хостинга, Basic Auth или проверки, требующей ручного прохождения. Успешный запрос с самого сервера не доказывает доступность для телефона.

Следующая команда выполняет GET и показывает заголовки, проверяя сертификат штатным способом. Замените адрес на публичную страницу без токенов. Это Bash; в PowerShell используйте curl.exe вместо псевдонима curl.

Bash · Проверка первого HTTP-ответа
curl --connect-timeout 5 --max-time 15 -sS -D - -o /dev/null \
  https://mini.example.com/

При ошибке DNS проверьте записи домена и доступность из нужной сети. При ошибке TLS — имя сертификата, срок и цепочку на веб-сервере. Не используйте -k как исправление: отключение проверки у диагностического клиента не исправляет Telegram.

Если ответ 301/302, проверьте Location и всю цепочку переходов до конечного HTTPS-адреса. Если 401/403 — выясните, не блокируют ли страницу авторизация, WAF или региональные правила. Если 404 — сверяйте путь, включая завершающий слеш и базовый каталог приложения. Если 200 — откройте тело ответа: код статуса не отличает вашу страницу от HTML-заглушки.

Проверяем HTML, CSS и JavaScript

В браузерных инструментах разработчика откройте Network и перезагрузите страницу. Найдите основной документ, JavaScript, CSS и первый API-запрос. Если документ загружается, а скрипт возвращает 404, сравните URL файла с опубликованной сборкой. Частая причина — новый HTML ссылается на хешированный файл, который ещё не загружен или уже удалён.

При ошибке MIME посмотрите тело ресурса: вместо JavaScript сервер мог вернуть HTML главной страницы через универсальный fallback. Исправьте маршрутизацию статических файлов и Content-Type. Проверяйте также относительные пути при открытии вложенного URL, а не только корня сайта.

Если проблема появилась после релиза, сопоставьте HTML, manifest и ресурсы одной версии. Проверьте CDN, браузерный кэш и service worker, если он используется. Очистка кэша на своём телефоне полезна как эксперимент, но не исправляет несовместимую выкладку для остальных пользователей.

HTTPS-страница не должна загружать обязательные скрипты или API через HTTP. Mixed content, блокировки Content Security Policy и недоступность внешнего CDN отображаются в Console/Network. Разрешайте только нужные источники; не отключайте всю CSP для устранения одного заблокированного ресурса.

Находим первую ошибку и показываем понятный экран

В Console ищите первую ошибку до каскада последующих. Если не определён Telegram.WebApp, проверьте загрузку официального скрипта и порядок выполнения. Если падает импорт модуля — сначала исправьте путь или синтаксис. Если ошибка возникает на обращении к данным пользователя, проверьте наличие полей и способ запуска.

Ниже диагностическая оболочка для отдельной тестовой страницы. Она показывает, загрузился ли документ, и сообщает о сбое запуска без вывода чувствительных объектов. Замените /app.js на модуль вашей страницы; это не полный Mini App и не обход серверной авторизации.

HTML · Видимая стадия загрузки
<!doctype html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Проверка запуска</title>
</head>
<body>
  <p id="boot" role="status">HTML загружен. Запускаем интерфейс…</p>
  <noscript>Для этой страницы необходим JavaScript.</noscript>
  <script>
    const boot = document.getElementById('boot');
    window.addEventListener('error', () => {
      boot.textContent = 'Ошибка запуска. Передайте поддержке время и версию приложения.';
    });
    window.addEventListener('unhandledrejection', () => {
      boot.textContent = 'Не удалось завершить загрузку. Попробуйте повторить позже.';
    });
  </script>
  <script src="https://telegram.org/js/telegram-web-app.js?64"></script>
  <script type="module">
    try {
      const app = window.Telegram?.WebApp;
      if (!app) throw new Error('Telegram bridge unavailable');
      const module = await import('/app.js');
      await module.mount();
      app.ready();
      boot.textContent = 'Интерфейс готов';
    } catch (error) {
      boot.textContent = 'Интерфейс не запустился. Проверьте загрузку ресурсов.';
    }
  </script>
</body>
</html>

mount должен построить основные элементы экрана и показать отдельное состояние ожидания данных. Не заставляйте его бесконечно ждать CRM перед ready(). Метод ready сообщает Telegram о готовности интерфейса; он не проверяет токен и не исправляет упавший JavaScript. Если CSP запрещает inline-скрипты, вынесите обработчики в разрешённый файл или используйте предусмотренный вашей политикой nonce.

Сверяем способ запуска и авторизацию

Проверьте URL в кнопке сообщения, персональной и общей кнопке меню, а также в Main Mini App, если этот способ используется. Один старый URL может остаться только у части пользователей. getChatMenuButton позволяет сверить кнопку конкретного личного чата; корректный общий адрес не доказывает, что персональная настройка совпадает.

Открытие страницы напрямую во внешнем браузере проверяет отображение, но не воспроизводит запуск из Telegram. Отсутствующий initData в таком запуске не следует заменять произвольным user_id. Разные способы открытия дают разный контекст; например, sendData не является универсальной отправкой для любой Mini App.

Если HTML и скрипты загрузились, а сервер возвращает 401, проверьте подпись initData, токен бота и auth_date. При 419 проверьте CSRF и cookie-сессию. При CORS-ошибке сравните фактические origin страницы и API; настройте разрешённый origin и credentials по выбранной схеме, вместо Access-Control-Allow-Origin: * для сессий.

Проверяем различия клиентов и темы

Сравните актуальные мобильный и настольный Telegram и, если он нужен аудитории, Telegram Web. Проверьте поддерживаемые методы JavaScript API перед вызовом и предусмотрите запасное поведение. Если приложение использует новый API без проверки версии, старый клиент может остановить весь запуск.

Проверьте светлую и тёмную темы: белый текст на белом фоне иногда выглядит как пустая страница. Осмотрите размеры корневого контейнера, перекрывающий слой загрузки, скролл и экранную клавиатуру. Загруженный DOM с нулевой высотой — другая проблема, чем отсутствующий HTML.

Для Web отдельно учитывайте размещение в браузере и ограничения cookie. Для мобильного устройства используйте доступные для его платформы средства отладки; не рассчитывайте, что инструменты настольного браузера автоматически показывают внутренний webview телефона.

Проверяем исправление и границы BotGate

Повторите тот же запуск, в той же сети и клиенте, где возникал сбой. Затем проверьте второй клиент и холодную загрузку. Успех означает, что виден интерфейс, завершился вход, прошёл запрос данных и пользователь получил понятный результат. Один HTTP 200 или вызов ready не подтверждают весь сценарий.

Если BotGate используется для отправки сообщений, он обслуживает серверные вызовы Bot API. HTML, ресурсы, сессия и API вашей формы проверяются отдельно. Если форма сохранилась, но уведомление не пришло, переходите к диагностике исходящих запросов.

  • Telegram Mini Apps — инициализация, способы запуска и API клиента.

  • CORS — ограничения запросов между origin.