Архитектура Mini App
Telegram Mini Apps — это революционная платформа для распространения Web3-приложений через мессенджер с 900+ миллионами пользователей. В отличие от традиционных dApps, которые требуют установки кошелька и перехода на отдельный сайт, Mini App открывается прямо в Telegram одним нажатием. Понимание архитектуры Mini Apps — это ключ к созданию приложений с массовой аудиторией.
Telegram Mini Apps (TMA) — это веб-приложения, работающие внутри мессенджера Telegram. Более 500 миллионов пользователей ежемесячно взаимодействуют с Mini App, что делает эту платформу одной из крупнейших экосистем для веб-приложений в мире.
В этом модуле мы разберём архитектуру Mini App, жизненный цикл, интеграцию с ботами и блокчейном TON.
От TWA к TMA
В 2022 году Telegram представил Telegram Web Apps (TWA) — возможность открывать веб-страницы прямо в чате. В 2024 году платформа была переименована в Mini Apps (TMA), отражая рост от простых веб-виджетов до полноценных приложений:
| Период | Название | Возможности |
|---|---|---|
| 2022 | Telegram Web Apps (TWA) | Базовый WebView, простые формы |
| 2023 | TWA + Payments | Платежи, расширенный API |
| 2024+ | Mini Apps (TMA) | Stars, CloudStorage, полноценная платформа |
TWA vs TMA
“TWA” и “TMA” — это одна и та же технология. В документации и статьях вы встретите оба термина. Актуальное название — Mini App.
Архитектура: WebView, а не iframe
Mini App работает не в iframe, а в нативном WebView — встроенном браузерном движке внутри клиента Telegram. Это принципиальное архитектурное отличие:
WebView обеспечивает:
- Мост (bridge) между JavaScript вашего приложения и нативным кодом Telegram
- Инъекцию скрипта
telegram-web-app.js, создающего объектwindow.Telegram.WebApp - Контроль — Telegram управляет навигацией, кнопками, темой и жизненным циклом
Ключевые компоненты
telegram-web-app.js
Telegram автоматически инъектирует скрипт через тег <script>, который создаёт объект window.Telegram.WebApp. Этот объект — единственный интерфейс между вашим приложением и Telegram:
@telegram-apps/sdk-react
Прямой доступ к window.Telegram.WebApp работает, но не рекомендуется для продакшена. Пакет @telegram-apps/sdk-react предоставляет:
- TypeScript-типы для всех методов и событий
- React-хуки для реактивной работы с API
- Обратную совместимость между версиями Bot API
- Mock-режим для локальной разработки без Telegram
Используйте @telegram-apps/sdk-react
Прямой доступ к window.Telegram.WebApp не даёт типизации, может сломаться при обновлении API и не работает вне Telegram. SDK абстрагирует эти проблемы.
Платформенные ограничения
Mini App работает в контролируемом окружении, а не в обычном браузере:
| Ограничение | Описание |
|---|---|
| Нет прямого localStorage | Используйте CloudStorage API для персистентных данных |
| Viewport | Размер окна зависит от платформы и может меняться динамически |
| Навигация | Нет адресной строки, кнопка “назад” управляется через BackButton API |
| Закрытие | Пользователь может свайпнуть вниз для закрытия (на мобильных) |
| Сеть | Все запросы идут через обычный интернет, не через Telegram |
Для хранения данных между сессиями используйте CloudStorage API — он синхронизирует данные между устройствами пользователя через облако Telegram.
Архитектура взаимодействия
Mini App — это часть экосистемы, состоящей из четырёх компонентов:
- Telegram Client загружает URL вашего Mini App в WebView
- Mini App получает данные пользователя через
initDataи отправляет их на бэкенд - Backend валидирует
initDataчерез HMAC-SHA256 и взаимодействует с Telegram Bot API - Telegram API обрабатывает команды бота, платежи, уведомления
Типичные сценарии использования
Mini App применяется, когда ботовых команд недостаточно:
- Игры — полноценный игровой UI внутри Telegram
- Платёжные интерфейсы — оплата через Telegram Stars или TON
- DeFi-дашборды — управление активами с TON Connect
- NFT-маркетплейсы — просмотр и торговля коллекциями
- Формы и опросы — сложные интерфейсы ввода данных
- Электронная коммерция — каталог товаров с корзиной
Mini App — не самостоятельный сайт
Mini App работает только внутри контролируемого WebView Telegram. Оно не может существовать как отдельный веб-сайт — ему нужен бот, Telegram-клиент и bridge между нативным кодом и JavaScript.
Итоги
| Свойство | Mini App | Обычный сайт |
|---|---|---|
| Запуск | Через бота в Telegram | Через браузер по URL |
| Окружение | Нативный WebView | Обычный браузер |
| Авторизация | initData от Telegram | Логин/пароль или OAuth |
| UI-контроллы | MainButton, BackButton | HTML-элементы |
| Хранение | CloudStorage API | localStorage, cookies |
| Платежи | Telegram Stars (XTR) | Stripe, PayPal и др. |
| Аудитория | 500M+ пользователей Telegram | Весь интернет |
В следующем уроке мы подробно разберём жизненный цикл Mini App — от нажатия кнопки до закрытия.
Частые ошибки
- Разрабатывают Mini App как обычный сайт, не адаптируя UI под мобильный контекст Telegram: размер экрана, жесты и навигация отличаются от браузера.
- Не используют Telegram WebApp API для интеграции с нативными функциями (BackButton, MainButton, HapticFeedback), из-за чего приложение выглядит чужеродным.
- Забывают вызвать Telegram.WebApp.ready() при загрузке: без этого Telegram не скроет загрузочный экран.
- Не валидируют initData на сервере: данные инициализации можно подделать на клиенте, что открывает возможности для атак.
После понимания технической архитектуры Mini App возникает вопрос системного дизайна: как разделить логику между ботом, бэкендом и контрактом, как продумать платежи (Stars, TON, Jetton), retention-петли и многошаговые сценарии. Это уровень System Design Mini Apps.
System Design: архитектура Mini Apps