Полноэкранный режим мини-приложения Telegram: как включить и где он нужен

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

Два разных понятия

Развёрнутое окно. Приложение занимает всю доступную высоту, но шапка Telegram с названием и кнопкой закрытия остаётся. Это делается методом expand из библиотеки Telegram для мини-приложений. Его обычно вызывают сразу после загрузки.

Полноэкранный режим. Приложение занимает весь экран устройства, шапка Telegram скрыта, остаются только системные элементы управления. Для этого в Bot API появились методы requestFullscreen и exitFullscreen, а также свойство isFullscreen и событие изменения режима. Полноэкранный режим уместен для игр, медиа, карт, видео и приложений с погружением.

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

1. Подключите скрипт Telegram для мини-приложений на странице
2. После загрузки вызовите метод ready, чтобы сообщить Telegram, что интерфейс готов
3. Вызовите метод expand
4. Проверьте свойство isExpanded, если логика зависит от размера окна

Также стоит отключить закрытие приложения вертикальным свайпом, если в интерфейсе есть прокрутка или жесты: для этого есть отдельный метод. Иначе пользователь, листая каталог, может случайно закрыть окно.

Как включить полноэкранный режим

Вызов requestFullscreen переводит приложение в полный экран. Лучше делать это по действию пользователя или в местах, где это действительно нужно, например при открытии видео или игры. Метод exitFullscreen возвращает обычный режим. Подпишитесь на событие изменения режима, чтобы перестраивать интерфейс, и обработайте случай, когда полноэкранный режим недоступен — например, на старой версии Telegram или в настольном клиенте.

Безопасные зоны

В полноэкранном режиме часть экрана занимают вырез камеры, системные индикаторы и элементы управления Telegram. Чтобы кнопки и текст не оказались под ними, используйте значения безопасных зон, которые передаёт Telegram: отступы для области устройства и для области контента. Они доступны и как CSS-переменные, что упрощает вёрстку. Проверьте интерфейс на телефонах с вырезом и без.

Ориентация экрана

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

Когда полноэкранный режим не нужен

• Магазин, запись, анкета — достаточно развёрнутого окна
• Приложение, где пользователь часто возвращается в чат
• Короткие действия: подтвердить, выбрать, оплатить

Шапка Telegram в этих случаях полезна: она показывает, что пользователь всё ещё в мессенджере, и даёт привычный способ закрыть окно.

Проверка на устройствах

Поведение отличается на Android, iOS, в настольной и веб-версии Telegram. Обязательно проверьте:

• открывается ли приложение развёрнутым сразу
• не перекрываются ли элементы вырезом и системными кнопками
• корректно ли работает кнопка «Назад» Telegram
• что происходит при повороте экрана
• как ведёт себя приложение в старой версии Telegram, где новых методов нет

Перед вызовом новых методов проверяйте версию API, которую поддерживает клиент: в библиотеке есть способ узнать её. Если метод не поддерживается, приложение должно работать в обычном режиме, а не выдавать ошибку.

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

• Вызов expand до загрузки интерфейса — окно разворачивается с белым экраном
• Отсутствие учёта безопасных зон — кнопки уходят под вырез камеры
• Полноэкранный режим для простой формы — пользователь не понимает, как выйти
• Отсутствие проверки версии — ошибки у пользователей со старыми клиентами
• Свайп вниз закрывает приложение во время прокрутки

Итог

Для большинства бизнес-задач достаточно развернуть окно по высоте и отключить закрытие свайпом. Полноэкранный режим используйте там, где он действительно улучшает опыт. Если нужно мини-приложение, которое корректно работает на всех устройствах, напишите — разработаем и протестируем.