Архитектура 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), отражая рост от простых веб-виджетов до полноценных приложений:

Архитектура: 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

Платформенные ограничения

Mini App работает в контролируемом окружении, а не в обычном браузере:

Архитектура взаимодействия

Mini App — это часть экосистемы, состоящей из четырёх компонентов:

1. Telegram Client загружает URL вашего Mini App в WebView
2. Mini App получает данные пользователя через initData и отправляет их на бэкенд
3. Backend валидирует initData через HMAC-SHA256 и взаимодействует с Telegram Bot API
4. Telegram API обрабатывает команды бота, платежи, уведомления

Типичные сценарии использования

Mini App применяется, когда ботовых команд недостаточно:

• Игры — полноценный игровой UI внутри Telegram
• Платёжные интерфейсы — оплата через Telegram Stars или TON
• DeFi-дашборды — управление активами с TON Connect
• NFT-маркетплейсы — просмотр и торговля коллекциями
• Формы и опросы — сложные интерфейсы ввода данных
• Электронная коммерция — каталог товаров с корзиной

Итоги

В следующем уроке мы подробно разберём жизненный цикл Mini App — от нажатия кнопки до закрытия.

Частые ошибки

1. Разрабатывают Mini App как обычный сайт, не адаптируя UI под мобильный контекст Telegram: размер экрана, жесты и навигация отличаются от браузера.
2. Не используют Telegram WebApp API для интеграции с нативными функциями (BackButton, MainButton, HapticFeedback), из-за чего приложение выглядит чужеродным.
3. Забывают вызвать Telegram.WebApp.ready() при загрузке: без этого Telegram не скроет загрузочный экран.
4. Не валидируют initData на сервере: данные инициализации можно подделать на клиенте, что открывает возможности для атак.