🔜 Telegram is about to introduce 10 new features for Mini Apps, enabling developers to create dozens of new kinds of apps and games on Telegram.

📺 Full-Screen Mode
📱 Home Screen Shortcuts
✍️ Subnoscription Plans
📍 Geolocation Access (with permissions)
📱 Device Orientation Data
💤 Emoji Status Access
🎨 Media Sharing
🎁 Sending Gifts
💭 Expanded Messaging Limits
💰 Ad Monetization

▶️ The last two items are already live with the remaining features launching within 2-4 weeks. Get your Mini Apps ready! 🚀

🟡 Настройка сплэш-экрана

Новая версия АПИ принесла нам возможность показывать свою иконку при запуске мини-аппа 😃

Делается очень просто через @BotFather → /mybots → выбрать бота → Bot Settings → Configure Mini App → Configure Splash Screen. Там же есть возможность проверить как иконка будет выглядеть 😉

Но не все так просто, как казалось бы. Иконка должна соответствовать определенным требованиям — иметь внутри себя один <path>. У меня даже с выполнением условия не сразу все загружалось, пришлось повозиться в разных графических редакторах чтобы верно сохранить 🤨

И даже после этого возникли баги (см. скриншоты). На Айос иконка отображается некорректно, а на Андроиде все прекрасно. Более того, даже та иконка, что предлагается как пример самим Телеграмом выглядит криво. Ждем когда поправят, но надежды на скорый фикс у меня как-то мало 😟 Написал про хак как это поправить.

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

———

🔄 Обновлено 09.05.25

По прямой ссылке теперь иконка так же отображается.

⬇️@MiniAppsForLife
🔘#инструкции

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

В недавнем обновлении АПИ отключили поддержку мета-свойства viewport-fit=contain и CSS-выражения env(safe-area-inset-*), но взамен дали нам две новых сущности:

1️⃣ Safe Area Inset

Предоставляет значения отступов для разных сторон экрана, чтобы контент приложения отображался без перекрытия системными элементами устройства, такими как вырезы, закругленные края, камеры или индикаторы навигации.

// Доступ через JS
Telegram.WebApp.safeAreaInset.top
Telegram.WebApp.safeAreaInset.bottom
Telegram.WebApp.safeAreaInset.left
Telegram.WebApp.safeAreaInset.right

/* Аналог на CSS */
var(--tg-safe-area-inset-top)
var(--tg-safe-area-inset-bottom)
var(--tg-safe-area-inset-left)
var(--tg-safe-area-inset-right)

2️⃣ Content Safe Area Inset

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

// Доступ через JS
Telegram.WebApp.contentSafeAreaInset.top
Telegram.WebApp.contentSafeAreaInset.bottom
Telegram.WebApp.contentSafeAreaInset.left
Telegram.WebApp.contentSafeAreaInset.right

/* Аналог на CSS */
var(--tg-content-safe-area-inset-top)
var(--tg-content-safe-area-inset-bottom)
var(--tg-content-safe-area-inset-left)
var(--tg-content-safe-area-inset-right)

*️⃣ Events

В дополнении к этому добавили два события safeAreaChanged и contentSafeAreaChanged, которые пригодятся для отслеживания изменений отступов. Например, при повороте экрана или раскрытии на полный.

🆗 Что со всем этим делать

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

.wrapper {
  padding-top: calc(var(--tg-safe-area-inset-top) + var(--tg-content-safe-area-inset-top));
  padding-right: calc(var(--tg-safe-area-inset-right) + var(--tg-content-safe-area-inset-right));
  padding-bottom: calc(var(--tg-safe-area-inset-bottom) + var(--tg-content-safe-area-inset-bottom));
  padding-left: calc(var(--tg-safe-area-inset-left) + var(--tg-content-safe-area-inset-left));
}

ℹ️ Нюансы и баги

— На клиенте для Мака, например, хочешь не хочешь, а пользователь в любом случае может включить фуллскрин из меню настроек, поэтому придется использовать var(--tg-content-safe-area-inset-top).

— На том же клиенте для Мака не обошлось без бага и в CSS-переменных значения для safe area inset попросту не приходят. Поэтому нужно прописать запасные значения, например, так var(--tg-safe-area-inset-top, 0px).

— В веб-версии (А) var(--tg-safe-area-inset-bottom) равен высоте окна приложения, что выглядит как явный баг.

🔄 Обновлено 26.01.25: баг исправлен.

— В целом, значения content safe area inset для right, buttom и left как будто бы ни для чего не нужны, потому что Телеграм использует только в верхней части свои элементы.

🆒 Итог

Из всего вышесказанного, я для себя сделал такой итоговый CSS:

.wrapper {
  padding-top: calc(var(--tg-safe-area-inset-top, 0px) + var(--tg-content-safe-area-inset-top));
  padding-right: var(--tg-safe-area-inset-right, 0px);
  padding-bottom: var(--tg-safe-area-inset-bottom, 0px);
  padding-left: var(--tg-safe-area-inset-left, 0px);
}

🔄 Обновлено 26.01.25: добавил bottom.

❓ Казалось бы, простая штука, а сколько много текста вышло. Пишите в комментах если есть чем дополнить?

@MiniAppsForLife
#инструкции