Передача темы и параметров из Telegram в Mini App: адаптивный UI

Вы открыли Mini App в Telegram и видите экран, который идеально подстраивается под ваш профиль - имя, аватар, язык, даже тема оформления. Но как это работает? Как Telegram передаёт эти данные в ваше приложение, и почему адаптивный интерфейс здесь не просто удобство, а обязательное условие для успеха?

Как Telegram отправляет данные в Mini App

Когда пользователь открывает Mini App через кнопку в боте, чате или канале, Telegram автоматически передаёт в приложение набор данных через URL-параметры. Эти данные не требуют никаких запросов или авторизаций - они уже есть в момент загрузки страницы. Главный параметр - tgWebAppData. Это закодированная строка, содержащая идентификатор пользователя, имя, фамилию, имя пользователя, язык, и даже тему (светлую или тёмную).

Эту строку нужно расшифровать с помощью JavaScript-библиотеки TelegramWebApp, которая уже встроена в среду Mini App. Вот как это выглядит на практике:

1. При загрузке страницы JavaScript читает параметр window.Telegram.WebApp.initData.
2. Использует TelegramWebApp.initDataUnsafe для извлечения объекта с данными пользователя.
3. Извлекает user.id, user.first_name, user.language_code, theme_params - и применяет их к интерфейсу.

Например, если пользователь использует тёмную тему в Telegram, параметр theme_params.bg_color вернёт значение #17212b. Ваше приложение может сразу применить этот цвет к фону - и пользователь не заметит резкого перехода между Telegram и Mini App. Это не магия, а точная передача данных.

Почему адаптивный UI - это не опция, а правило

Mini App работает на десятках разных устройств: от старых смартфонов с 5-дюймовыми экранами до флагманов с 7-дюймовыми дисплеями. Но главное - она работает внутри Telegram, а не как отдельное приложение. Это значит, что вы не управляете размером окна. Оно может быть 300px или 800px - всё зависит от того, где пользователь открыл вашу Mini App: в чате, в боте, в канале или в профиле.

Если вы сделаете фиксированную ширину в 500px, на маленьком экране пользователь будет прокручивать вправо-влево. На большом - появятся огромные пустые поля по бокам. Оба варианта - это провал.

Правильный подход - использовать viewport и TelegramWebApp.viewportHeight. Эти параметры меняются в реальном времени. Когда пользователь открывает клавиатуру, высота окна уменьшается. Когда он сворачивает чат - увеличивается. Ваш интерфейс должен реагировать на эти изменения без перезагрузки.

Вот как это делают успешные Mini App:

• Используют CSS flexbox и grid вместо фиксированных размеров.
• Задают минимальные и максимальные значения для блоков: min-width: 280px; max-width: 100%.
• Скрывают или сворачивают второстепенные элементы на маленьких экранах (например, боковое меню превращается в кнопку «☰»).
• Используют относительные единицы: rem, vw, % - вместо px.

Приложение Notion Mini App в Telegram, например, автоматически меняет раскладку текстового редактора: на маленьком экране - только панель инструментов и поле ввода, на большом - добавляется боковая панель с навигацией. Это не случайность - это продуманный адаптивный дизайн.

Как использовать параметры темы для единого стиля

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

Параметр theme_params содержит:

• bg_color - цвет фона
• text_color - цвет текста
• hint_color - цвет подсказок
• link_color - цвет ссылок
• button_color - цвет кнопок
• button_text_color - цвет текста на кнопках

Эти значения приходят в формате #rrggbb или rgba(). Вы можете применить их через JavaScript:

const theme = TelegramWebApp.themeParams;
document.documentElement.style.setProperty('--bg-color', theme.bg_color);
document.documentElement.style.setProperty('--text-color', theme.text_color);

А потом использовать в CSS:

body {
  background-color: var(--bg-color);
  color: var(--text-color);
}

button {
  background-color: var(--button_color);
  color: var(--button_text_color);
}

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

Как обрабатывать язык и локализацию

Параметр user.language_code возвращает код языка в формате ru, en, es, zh. Это ключ к локализации. Но не стоит полагаться только на него.

Некоторые пользователи используют английскую версию Telegram, но родной язык у них - украинский. Или наоборот. Поэтому важно:

• Предоставить в приложении выбор языка вручную - даже если вы используете автоматическое определение.
• Использовать библиотеки вроде i18next или простые JSON-файлы с переводами.
• Не забывать про направление текста: для арабского и иврита нужно менять direction: rtl в CSS.

Приложение Telegram Bot for Finance использует язык пользователя для выбора формата даты и валюты. Если язык - ru, то дата отображается как 12.03.2025, а если en - как 03/12/2025. Это мелочь, но она влияет на доверие.

Как передавать кастомные параметры при запуске

Telegram позволяет передавать не только стандартные данные, но и свои собственные параметры через URL. Например, вы можете создать ссылку вида:

https://yourapp.com?start_param=referral_123&campaign=summer_sale

Эти параметры попадают в initData как start_param и campaign. Это мощный инструмент для маркетинга. Вы можете отслеживать, откуда пришёл пользователь: из чата, из рекламы, из поста в канале.

Приложение Crypto Wallet Mini App использует start_param для начисления бонуса. Если пользователь пришёл по ссылке с кодом friend_789, ему автоматически добавляют 5 USDT. Это работает - и не требует авторизации.

Важно: все кастомные параметры должны быть проверены на сервере. Никогда не доверяйте клиентской стороне. Даже если вы показываете бонус в интерфейсе, реальное начисление должно происходить через API с проверкой подписи.

Что делать, если данные не пришли

Иногда initData пустой. Почему? Потому что пользователь открыл Mini App не через Telegram - например, через браузер. Или он использует стороннее приложение, которое эмулирует Telegram Web App.

Всегда проверяйте наличие данных:

if (!TelegramWebApp.initData) {
  // Показать сообщение: «Откройте приложение в Telegram»
  document.body.innerHTML = '
Это приложение работает только внутри Telegram.
';
  return;
}

Также добавьте обработку ошибок при расшифровке. Иногда строка повреждена, или приложение запущено в старой версии Telegram. В таких случаях лучше показать базовую версию интерфейса с предложением обновить приложение.

Пример: как выглядит рабочий Mini App

Представьте приложение для заказа кофе в Telegram. Пользователь нажимает кнопку - открывается Mini App.

• В верхней части - его имя и аватар, извлечённые из user.first_name и user.photo_url.
• Фон - тёмный, потому что пользователь в тёмной теме Telegram.
• Кнопки - синие, как в его Telegram.
• На маленьком экране - только выбор напитка и кнопка «Заказать».
• На большом - добавляется карта с ближайшими кафе, история заказов, промокоды.
• Если пользователь пришёл по ссылке с кодом coffee_2025, ему автоматически дают скидку 15%.

Это не сложный код. Это продуманная последовательность: данные → адаптация → опыт. И именно так создаются Mini App, которые пользователи не закрывают через 3 секунды.

Что дальше: как тестировать и оптимизировать

Тестируйте Mini App на реальных устройствах. Не только на iPhone и Android, но и на планшетах, на старых моделях, на устройствах с разным разрешением экрана.

Используйте Telegram Desktop для проверки на ПК. Некоторые функции работают иначе на десктопе.

Мониторьте ошибки через console.error и отправляйте их на сервер. Сколько пользователей получают пустой initData? Сколько не видят кнопки на маленьких экранах? Это ваши ключевые метрики.

Не забывайте: Mini App - это не веб-сайт. Это расширение Telegram. Пользователь не пришёл за сложным интерфейсом. Он пришёл за быстрым, понятным, единым с Telegram опытом. Сделайте его таким - и ваша Mini App станет востребованной.