Не открывается мини-приложение в Telegram: белый экран на iPhone и ПК

Мини-приложение в Telegram не открывается: с чего начать

Сначала уточните, что не открывается: сам Telegram или мини-приложение внутри него. Ниже разбираем Mini App; белый экран вместо списка чатов — другая задача.

Пользователю: начните с раздела «Что делать пользователю, если мини-приложение не грузится». Разработчику: зафиксируйте платформу и точный текст ошибки; затем проверьте соответствующий раздел — WebView, хранилище, initData или размер окна. Это порядок диагностики, а не диагноз по одному белому экрану.

Что делать пользователю, если мини-приложение не грузится

Мини-приложение делает не Telegram, а сторонний разработчик. В справке Telegram так и сказано: мини-приложения — «full applications that run inside Telegram, built by outside developers». Большинство причин белого экрана из этой статьи может исправить только он. Со своей стороны проверьте четыре вещи.

1. Обновите Telegram и повторите запуск. Это рекомендация для проверки совместимости: доступные возможности Mini App зависят от версии клиента; обновление не гарантирует устранения сбоя.
2. Для сравнения откройте то же мини-приложение на другом устройстве или в Telegram Web. Запишите результат, не делайте по нему вывод о причине.
3. Если вместо Mini App открывается сайт в браузере, сообщите об этом владельцу бота. Разработчику стоит проверить тип кнопки: в Bot API поля url и web_app имеют разное назначение.
4. Отправьте владельцу: имя бота, название Mini App, устройство, ОС, версию Telegram, время сбоя, точный текст ошибки и снимок экрана. Укажите, воспроизводится ли проблема на другом устройстве. Это рекомендуемый шаблон обращения.

Очистка кэша. Telegram описывает её как способ освободить место на устройстве, не выходя из аккаунта: «Настройки → Данные и память → Использование памяти → Очистить кэш»; переписка хранится в облаке и не пропадает (справка Telegram). Помогает ли очистка кэша мини-приложению, в справке не сказано. Выходить из аккаунта ради этого не нужно: по справке при выходе пропадают все секретные чаты.

«Произошёл сбой WebView»: что проверить разработчику

Не выбирайте исправление только по этой фразе. Сначала снимите ошибку консоли и неудачный сетевой запрос на устройстве, где воспроизводится сбой. Это рекомендуемый первый шаг диагностики.

• SecurityError при доступе к localStorage: проверьте доступность хранилища. Политика браузера может запретить сохранение данных; приватный режим сам по себе не означает обязательный запрет localStorage.
• Отказ встраивания из-за frame-ancestors: сверяйте разрешённых родителей страницы с фактическим окружением. Директива проверяет цепочку предков, а не список API-доменов приложения.
• Для исследования сбоя используйте официальную инструкцию Telegram Debug Mode for Mini Apps. Eruda ниже — дополнительный инструмент.

Сводная матрица: почему не работают мини-приложения в телеграмме и как это починить

В таблице ниже собраны основные симптомы сбоев, уязвимые платформы и быстрые способы диагностики:

Ошибка №1. Заголовки CSP и X-Frame-Options: когда браузер молча блокирует iframe

В десктопном приложении (Telegram Desktop для Windows и macOS) и в браузерных клиентах (web.telegram.org) Mini App открывается внутри стандартного HTML-фрейма <iframe>.

Большинство современных веб-серверов (Nginx, Caddy, Apache), облачных прокси (Cloudflare) и фреймворков (Next.js, Remix, Nuxt) по умолчанию настроены на максимальную безопасность и отдают заголовки, предотвращающие атаки кликджекинга (Clickjacking):

• X-Frame-Options: DENY или X-Frame-Options: SAMEORIGIN
• Content-Security-Policy: frame-ancestors 'none' или frame-ancestors 'self'

Как только браузер видит такой заголовок в ответе страницы, загружаемой внутри <iframe>, он мгновенно и безусловно блокирует рендеринг документа. В консоли десктопного браузера появляется красная ошибка Refused to display in a frame because it set 'X-Frame-Options' to 'sameorigin', а пользователь видит абсолютно чистый белый прямоугольник.

При этом на мобильном телефоне (где используется нативный WebView без родительского фрейма) приложение может открываться без проблем. Разработчик проверяет телефон, видит работающий интерфейс и не понимает, почему клиенты на ноутбуках жалуются на белый экран.

Как починить

Заголовок X-Frame-Options является устаревшим стандартом: он не поддерживает указание нескольких разрешённых доменов. Современный стандарт W3C требует использования директивы frame-ancestors в заголовке Content-Security-Policy.

Для веб-сервера Nginx конфигурация виртуального хоста Mini App должна выглядеть следующим образом:

server {
    server_name app.vash-domen.ru;

    # Отключаем устаревший заголовок X-Frame-Options, если он выставлен бэкендом
    proxy_hide_header X-Frame-Options;

    # Разрешаем встраивание во фрейм только нашему сайту и клиентам Telegram
    add_header Content-Security-Policy "frame-ancestors 'self' https://web.telegram.org https://*.telegram.org https://telegram.org;" always;

    # Базовые заголовки защиты от подмены типов контента
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Если ваше приложение работает на Next.js без проксирующего веб-сервера, скорректируйте заголовки в файле next.config.js:

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "frame-ancestors 'self' https://web.telegram.org https://*.telegram.org https://telegram.org;",
          },
        ],
      },
    ];
  },
};

Ошибка №2. Строгая песочница Apple WebKit и внезапный краш localStorage на iPhone

Это частая причина «белого экрана на iPhone» в мобильном трафике.

В операционной системе iOS браузерный движок WebKit (WKWebView) работает в режиме повышенной изоляции персональных данных. При определённых настройках приватности или строгих политиках защиты от отслеживания WebKit может блокировать доступ к веб-хранилищу:

• window.localStorage
• window.sessionStorage

При любой попытке прочитать или записать значение:

const token = localStorage.getItem('auth_token');

WebKit не просто возвращает null — он выбрасывает фатальное исключение уровня браузера: DOMException: The operation is insecure. (или SecurityError: The operation is insecure).

Почему приложение падает намертво

В современных одностраничных приложениях (SPA) популярные менеджеры состояния (Zustand с мидлваром persist, Redux-Persist, Pinia Persistedstate) вызывают обращение к localStorage синхронно на этапе импорта и инициализации JavaScript-модулей.

Это происходит до того, как отработает React-компонент <ErrorBoundary> и до того, как фреймворк смонтирует первый DOM-узел в страницу. В результате происходит неперехваченное исключение (Uncaught Exception), выполнение JavaScript-бандла аварийно прекращается, рендерер не стартует, и в телеграме на айфоне вместо рабочего сервиса — пустой интерфейс, белый экран.

Как починить

Шаг 1. Обёртка SafeStorage с fallback. Если в вашем сценарии возможна блокировка localStorage, используйте модуль безопасного хранилища с перехватом ошибок и переключением на оперативную память (in-memory Map):

// safeStorage.ts — безопасная работа с хранилищем в iOS WebKit
class SafeStorage implements Storage {
  private memory = new Map<string, string>();
  private isAvailable: boolean;

  constructor() {
    this.isAvailable = this.checkStorage();
  }

  private checkStorage(): boolean {
    try {
      if (typeof window === 'undefined' || !window.localStorage) return false;
      const testKey = '__tma_storage_test__';
      window.localStorage.setItem(testKey, '1');
      window.localStorage.removeItem(testKey);
      return true;
    } catch {
      // WebKit заблокировал доступ к хранилищу из-за настроек приватности
      return false;
    }
  }

  get length(): number {
    return this.isAvailable ? window.localStorage.length : this.memory.size;
  }

  getItem(key: string): string | null {
    if (this.isAvailable) {
      try {
        return window.localStorage.getItem(key);
      } catch {
        return this.memory.get(key) ?? null;
      }
    }
    return this.memory.get(key) ?? null;
  }

  setItem(key: string, value: string): void {
    if (this.isAvailable) {
      try {
        window.localStorage.setItem(key, value);
        return;
      } catch {
        // Fallback в память, если квота переполнена или права отозваны
      }
    }
    this.memory.set(key, String(value));
  }

  removeItem(key: string): void {
    if (this.isAvailable) {
      try {
        window.localStorage.removeItem(key);
      } catch {}
    }
    this.memory.delete(key);
  }

  clear(): void {
    if (this.isAvailable) {
      try {
        window.localStorage.clear();
      } catch {}
    }
    this.memory.clear();
  }

  key(index: number): string | null {
    if (this.isAvailable) {
      try {
        return window.localStorage.key(index);
      } catch {}
    }
    return Array.from(this.memory.keys())[index] ?? null;
  }
}

export const safeStorage = new SafeStorage();

Шаг 2. Переход на нативный Telegram CloudStorage. Для долговременного сохранения пользовательских настроек и состояния корзины используйте нативный API Telegram: Telegram.WebApp.CloudStorage. Он хранит данные на серверах Telegram, привязан к идентификатору аккаунта, не зависит от настроек кук Safari и синхронизируется между смартфоном и десктопом пользователя.

Ошибка №3. initData expired, missing initData и ошибка 401

При запуске Mini App клиент Telegram передаёт приложению строку инициализации: window.Telegram.WebApp.initData.

Она содержит профиль пользователя (id, имя, username, язык интерфейса), время генерации строки auth_date и криптографическую подпись hash. Бэкенд обязан проверить подлинность этих данных, чтобы злоумышленник не мог подделать чужой user_id.

Если валидация завершается неудачей, бэкенд возвращает статус 401 Unauthorized. Если на фронтенде не предусмотрен явный экран ошибки авторизации, пользователь видит вечный скелетон или пустой экран.

4 подводных камня валидации HMAC-SHA256

1. Неверный секретный ключ. Распространённая ошибка новичков — вычисление HMAC от токена бота напрямую. По спецификации Telegram секретный ключ вычисляется как HMAC-SHA256 от токена бота, где ключом хеширования выступает фиксированная константная строка "WebAppData":
   secret_key = HMAC_SHA256(key="WebAppData", msg=BOT_TOKEN).
2. Алфавитная сортировка параметров. Перед склеиванием параметров в строку data_check_string через символ переноса строки \n, все пары key=value обязаны быть отсортированы строго лексикографически по имени ключа. Параметр hash при этом обязательно исключается.
3. Протухание сессии по auth_date. Telegram генерирует initData один раз при первом открытии Mini App. Если пользователь оставил приложение свернутым на 2 часа и вернулся к оформлению заказа, таймштамп auth_date устаревает. Если на бэкенде установлен слишком жесткий таймаут (например, 15 или 30 минут), все последующие API-запросы будут отвергнуты.
4. Кодирование спецсимволов и кириллицы. Поле user передаётся внутри initData в виде экранированной JSON-строки. Если ваш HTTP-фреймворк производит автоматическое двойное URL-декодирование пробелов, кавычек или эмодзи, исходная строка проверки изменится, и рассчитанный хэш не сойдётся с оригиналом.

Пример алгоритма валидации на Python

Ниже приведён пример проверки подписи для FastAPI или другого Python-бэкенда:

import hmac
import hashlib
import json
import time
from urllib.parse import parse_qsl

def validate_telegram_init_data(init_data: str, bot_token: str, max_age_seconds: int = 86400) -> dict:
    """
    Проверяет подлинность initData от Telegram Mini App.
    Возвращает словарь с параметрами при успехе.
    Выбрасывает ValueError при фальсификации данных или протухании сессии.
    """
    if not init_data:
        raise ValueError("Пустая строка initData")

    # 1. Разбираем параметры строки запроса
    parsed_data = dict(parse_qsl(init_data, keep_blank_values=True))

    if "hash" not in parsed_data:
        raise ValueError("В параметрах initData отсутствует обязательное поле hash")

    received_hash = parsed_data.pop("hash")

    # 2. Проверяем срок жизни данных
    auth_date = int(parsed_data.get("auth_date", 0))
    if time.time() - auth_date > max_age_seconds:
        raise ValueError("Сессия устарела (auth_date expired). Требуется перезапуск приложения.")

    # 3. Собираем data_check_string с алфавитной сортировкой ключей
    check_items = [f"{k}={v}" for k, v in sorted(parsed_data.items())]
    data_check_string = "\n".join(check_items)

    # 4. Вычисляем секретный ключ: HMAC-SHA256("WebAppData", bot_token)
    secret_key = hmac.new(b"WebAppData", bot_token.encode("utf-8"), hashlib.sha256).digest()

    # 5. Вычисляем контрольный хэш от собранной строки
    calculated_hash = hmac.new(secret_key, data_check_string.encode("utf-8"), hashlib.sha256).hexdigest()

    # 6. Защищенное от атак по времени сравнение хэшей
    if not hmac.compare_digest(calculated_hash, received_hash):
        raise ValueError("Фальсификация подписи: контрольный хэш не совпадает")

    # 7. Преобразуем JSON-поле user в словарь
    if "user" in parsed_data:
        parsed_data["user"] = json.loads(parsed_data["user"])

    return parsed_data

initData expired и missing initData: разные проверки

missing initData указывает на отсутствующие данные инициализации. Владелец бота должен сверить способ запуска и передачу initData серверу; пользователь может повторить запуск из кнопки бота. Это рекомендация диагностики, не гарантия исправления.

При проверке давности сервер использует auth_date. Лимит допустимого возраста задаёт разработчик: 86400 секунд в примере выше — параметр этого кода, а не обязательный срок Telegram. Проверяйте отдельно давность и подпись.

По сообщению no token или одному статусу 401 нельзя установить, что сломан именно initData. Сверьте ответ конкретного сервера; на фронтенде покажите ошибку и действие для повторного входа вместо вечной загрузки. Это рекомендация обработки ошибки.

Ошибка №4. Вьюпорт iOS, сдвиг экранной клавиатуры и заблокированный скролл

В веб-разработке традиционно используется правило height: 100vh или 100% для задания высоты экрана. Однако внутри браузерного движка WebKit на iPhone это правило приводит к двум фатальным проблемам интерфейса:

1. Сдвиг экрана при открытии клавиатуры. Когда пользователь ставит курсор в поле ввода (<input> или <textarea>), операционная система iOS поднимает виртуальную клавиатуру и сдвигает контейнер WebView вверх. Когда клавиатура закрывается (по нажатию «Готово» или тапу вне поля), WebKit не возвращает вьюпорт в исходное положение. В результате нижняя навигационная панель и кнопка «Оплатить заказ» физически улетают за пределы экрана.
2. Паразитный вертикальный скролл (Rubber Banding). Высота 100vh в Safari включает высоту строки состояния и системной панели Home Bar. Приложение не помещается в экран, и при попытке прокрутки интерфейс дёргается и пружинит вверх-вниз.

Как починить

1. Вызов метода expand(). При необходимости развернуть Mini App на доступную высоту экрана смартфона вызовите метод expand() после готовности интерфейса:

if (window.Telegram?.WebApp) {
  const tg = window.Telegram.WebApp;
  tg.ready();
  tg.expand();
}

2. Использование CSS-переменных Telegram. Telegram WebApp SDK автоматически передаёт в стили документа вычисленные значения высоты: --tg-viewport-height и --tg-viewport-stable-height.

Настройте корневой контейнер вашего приложения в CSS:

/* Контейнер приложения Telegram Mini App */
.tma-wrapper {
  min-height: var(--tg-viewport-stable-height, 100vh);
  height: var(--tg-viewport-height, 100vh);
  width: 100%;
  overflow-x: hidden;
  overflow-y: auto;
  /* Блокируем паразитную оттяжку страницы в WebKit */
  overscroll-behavior-y: none;
  /* Учитываем системную плашку iPhone Home Bar */
  padding-bottom: env(safe-area-inset-bottom, 16px);
}

Mini App на ПК открывается не полностью или не на весь экран

Отделите размер окна от отказа запуска. expand() увеличивает доступную высоту Mini App; requestFullscreen() запрашивает полноэкранный режим и требует поддержки Bot API 8.0+. Это разные возможности.

Разработчику рекомендуем проверить поддержку API и воспроизвести проблему с размерами окна в клиенте пользователя. Один вызов expand() не следует обещать как универсальное исправление вёрстки ПК.

3. Корректный мета-тег Viewport. В файле index.html или в метаданных корневого лейаута задайте жесткий вьюпорт без возможности случайного масштабирования жестами:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">

Ошибка №5. Вместо Mini App открывается браузер: проверьте кнопку

Распространённая жалоба пользователей: «Я нажимаю кнопку в боте, но вместо аккуратного окна внутри Telegram у меня открывается Safari или Chrome, а там сайт выдаёт ошибку».

Причина банальна: кнопка в Telegram настроена как обычный переход по ссылке (url), а не как вызов Web App.

Когда кнопка передаёт обычный URL:

# ОШИБКА: открывает системный браузер вместо Mini App
InlineKeyboardButton(text="Открыть каталог", url="https://app.site.ru")

Telegram открывает внешний браузер операционной системы. В нём полностью отсутствует объект window.Telegram.WebApp (он равен undefined). Если ваш код обращается к Telegram.WebApp.ready() без проверки существования объекта, скрипт падает с ошибкой TypeError: Cannot read properties of undefined (reading 'ready').

Как настроить кнопки правильно

В коде бота (на примере библиотеки aiogram 3.x) кнопка должна быть явно типизирована через объект WebAppInfo:

from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton, WebAppInfo

# ПРАВИЛЬНО: открывает Mini App внутри Telegram
keyboard = InlineKeyboardMarkup(inline_keyboard=[
    [
        InlineKeyboardButton(
            text="🛍️ Открыть магазин",
            web_app=WebAppInfo(url="https://app.vash-domen.ru")
        )
    ]
])

Для настройки постоянной кнопки меню в левом нижнем углу чата откройте @BotFather:

1. Отправьте команду /setmenubutton.
2. Выберите вашего бота.
3. Отправьте прямую HTTPS-ссылку на веб-приложение.

Как подключить отладчик прямо на смартфоне

Если на iPhone приложение всё равно не открывается, а подключать телефон к компьютеру через кабель и настраивать Safari Web Inspector нет времени, используйте мобильную консоль Eruda.

Добавьте в точку входа вашего приложения скрипт условного подключения отладчика:

// Подключение мобильного отладчика по параметру ?debug=1
if (typeof window !== 'undefined' && new URLSearchParams(window.location.search).has('debug')) {
  const script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/npm/eruda';
  script.onload = () => {
    if (window.eruda) window.eruda.init();
  };
  document.head.appendChild(script);
}

Теперь, если в ссылке на Web App передать параметр debug (например, https://app.vash-domen.ru/?debug=1), прямо поверх интерфейса на экране смартфона появится плавающая кнопка консоли разработчика, в которой видны все сетевые запросы, ошибки в консоли и дерево DOM.

Ошибка №6. Неполная цепочка SSL (Intermediate CA) и строгий WebKit

Симптомы этой проблемы сбивают с толку даже опытных системных администраторов:

• На ноутбуке в Chrome сайт открывается с зелёным замочком.
• На Android-смартфоне всё работает быстро и без ошибок.
• На iPhone внутри Telegram Mini App — вечный белый экран, а в логах веб-сервера access.log нет вообще ни одного запроса.

Почему это происходит

Десктопные браузеры умеют самостоятельно восстанавливать неполную цепочку доверия сертификатов с помощью механизма AIA (Authority Information Access): если веб-сервер не отдал промежуточный сертификат (Intermediate CA), браузер докачивает его самостоятельно.

Если в конфигурации веб-сервера указан только листовой сертификат домена (cert.pem), а не полная цепочка (fullchain.pem), часть клиентов на iOS разрывает TLS-рукопожатие ещё до отправки HTTP-запроса. Проверяйте наличие промежуточных сертификатов.

Как проверить и исправить

Проверьте ваш домен через терминал с помощью утилиты openssl:

openssl s_client -connect app.vash-domen.ru:443 -servername app.vash-domen.ru

Если в выводе присутствует строка Verify return code: 21 (unable to verify the first certificate) — цепочка сертификата разорвана.

В конфигурационном файле Nginx обязательно укажите файл с полной цепочкой сертификатов:

# ОШИБКА: листовой сертификат вызовет белый экран на iOS
# ssl_certificate /etc/letsencrypt/live/app.vash-domen.ru/cert.pem;

# ПРАВИЛЬНО: полная цепочка доверия для всех устройств
ssl_certificate /etc/letsencrypt/live/app.vash-domen.ru/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/app.vash-domen.ru/privkey.pem;

Чек-лист проверки Telegram Mini App перед запуском трафика

Используйте этот контрольный чеклист перед релизом или запуском рекламной кампании:

• Тестирование на 4 средах исполнения: проверено открытие в iOS (WebKit), Android (Chromium), Telegram Desktop и Telegram Web.
• Корректные заголовки фрейма: в Content-Security-Policy прописана директива frame-ancestors https://*.telegram.org, заголовок X-Frame-Options отключен.
• Безопасная работа с хранилищем: вызовы localStorage обёрнуты в безопасный полифилл try/catch, долговременные данные переведены на CloudStorage.
• Валидация initData на сервере: ключ считается через HMAC-SHA256("WebAppData", bot_token), параметры отсортированы по алфавиту, таймаут сессии адекватен поведению пользователей.
• Адаптация вьюпорта: вызван Telegram.WebApp.expand(), для корневого контейнера задана высота var(--tg-viewport-height, 100vh), сброшен скролл overscroll-behavior-y: none.
• Проверка SSL-цепочки: на веб-сервере установлен бандл fullchain.pem, тест SSL Labs показывает рейтинг A/A+.
• Мобильный отладчик: внедрена возможность запуска консоли Eruda по параметру debug для оперативной диагностики на реальных устройствах.

Когда разработку и аудит стоит доверить инженерам «2САЙТ»

Telegram Mini App сегодня — это мощнейший инструмент продаж и обслуживания клиентов, позволяющий бизнесу отказаться от дорогой разработки мобильных приложений под iOS и Android в пользу Web Apps. Однако за кажущейся простотой веб-страницы скрываются жесткие технические ограничения гибридных систем, специфики Apple WebKit и строгой политики безопасности мессенджера.

Если вы планируете запуск или ваш текущий Mini App работает нестабильно, теряет пользователей на этапе входа и сливает рекламный бюджет:

• Команда студии «2САЙТ» выполняет профессиональную разработку Telegram Mini Apps под ключ: от проектирования отказоустойчивой архитектуры до бесшовной интеграции с CRM, платежными системами и 1С.
• Если вашему бизнесу требуются интеллектуальные сценарии общения и автоматические продажи внутри бота, изучите наши решения по внедрению AI-консультантов для бизнеса.
• А если вы столкнулись с проблемами в работе серверной части и логики самого бота, ознакомьтесь с нашим практическим руководством о том, почему чат-бот не отвечает и как провести экспресс-диагностику сбоев.

Для консультации и проведения технического аудита или заказа разработки Telegram Mini App под ключ свяжитесь с нашими инженерами через форму на сайте или Telegram-бота студии. Мы выявим скрытые уязвимости архитектуры до того, как они повлияют на ваших клиентов.