🪁 Запускаем веб-приложение напрямую из любого чата

Допустим, у вас уже есть свой мини-апп, но чтобы им воспользоваться пользователю нужно сперва перейти в бота, нажать кнопку «Старт», а затем открыть веб-приложение, кликнув на кнопку меню. Для кого-то этот путь может быть слегка утомительным.

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

1️⃣ Переходим в @BotFather и вызываем команду /newapp
2️⃣ Выбираем нужного бота. Вводим заголовок, короткое описание, фото (640×360) или гифку (не обязательно)
3️⃣ Вводим URL-адрес приложения, например https://app.pmdrk.ru (или любую другую внутреннюю страницу)
4️⃣ Придумываем уникальное короткое имя, например start или app
5️⃣ Готово! Теперь у вас есть ссылка https://t.me/PmdrkBot/start, которую можно скинуть в любой чат и мини-апп запустится сразу же, минуя переход в бота. Более того, такую ссылку можно разместить в интернете и при переходе по ней, веб-приложение откроется поверх списка чатов

В целом, таких адресов можно создать сколько угодно, должно отличаться только короткое имя. Все остальные детали есть в документации.

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

———

🔄 Обновлено 30.10.24

С выходом версии 7.8 к боту можно прикреплять основное мини-приложение через @BotFather командой /setminiapp. После чего в профиле появляется большая синяя кнопка «Открыть приложение», аналогом которой является ссылка на бота с параметром startapp.

Другими словами, если вы увидите в профиле любого бота такую кнопку, то можно смело брать ссылку вида https://t.me/<BOT_NAME>?startapp и вставлять ее где угодно.

#инструкции

🛍 Мини-магазин приложений

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

Назвать это магазином, конечно же, не получается. По сути, пока это выглядит как список популярных тапалок. Я до последнего надеялся, что это сделают похожим на то, как «Кошелек» разместили в разделе настроек и что это будет Apps Center.

Так или иначе, «магазин» можно найти, зайдя в поиске во вкладку «Приложения», что, вроде бы, логично, но как-то не самый очевидный и частый кейс для обычного пользователя.

Итак, чтобы профиль бота с мини-аппом выглядел красиво, как на видео, нужно привязать к боту веб-приложение. Делается это в Bot Father командой /setminiapp или /mybots → выбрать бота → Bot Settings → Configure Mini App.

После этого в профиле бота появится большая кнопка «Открыть приложение», а также возможность загрузить туда демонстрационные скриншоты на разных языках.

Кстати, если зайти в бота, то теперь под его названием показывается количество пользователей. Я так понимаю это размер месячной аудитории.

Еще в новой версии АПИ появилась возможность через мини-апп публиковать истории. Жаль, что не истории от самого бота 😀

А еще появился внутренний браузер. Теперь любая ссылка открывается внутри него — еще один шаг Телеграма держать пользователя внутри себя. Отключить можно в Настройках → Данные и память → Браузер.

❓ Что думаете про обновление? Может быть заметили что-то еще неочевидное?

#новости #инструкции

📱 Открываем мини-апп с домашнего экрана телефона

На видео, к сожалению, пока лишь мечты, но к ним есть возможность приблизиться 🙌

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

📱 На Айфоне через приложение «Команды»:

1. Запускаем приложение и жмем на плюсик для создания новой команды
2. Жмем на кнопку «Добавить действие» и выбираем «Интернет»
3. Находим в списке команду для Сафари «Открыть URL»
4. Вставляем готовую ссылку https://t.me/PmdrkBot/start в первое поле. Здесь же, в нижней панели, жмем на иконку «Поделиться» и выбираем пункт «На экран „Домой“»
5. Меняем название, загружаем иконку или выбираем значок, жмем «Добавить». Готово!

📱 На Андроиде через приложение Shortcut Maker:

1. Запускаем приложение и выбираем Websites
2. Вводим название и вставляем готовую ссылку https://t.me/PmdrkBot/start. Жмем на кнопку Place on Home Screen
3. Настраиваем иконку и, при желании, другие фукции. Жмем Create Shortcut. Готово!

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

———

🔄 Обновлено 30.10.24

С выходом версии 7.8 к боту можно прикреплять основное мини-приложение через @BotFather командой /setminiapp. После чего в профиле появляется большая синяя кнопка «Открыть приложение», аналогом которой является ссылка на бота с параметром startapp.

Другими словами, если вы увидите в профиле любого бота такую кнопку, то можно смело брать ссылку вида https://t.me/<BOT_NAME>?startapp и вставлять ее где угодно.

#инструкции

🌐 Локализация бота

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

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

На данный момент локализация поддерживает:
— Название
— Описание профиля
— Описание при открытии
— Команды
— Скриншоты
— Кнопку меню

Почти все можно настроить обычными запросами с вызовом соответствующего метода через АПИ по адресу https://api.telegram.org/bot<TOKEN>/<METHOD_NAME>.

Изначально стоит определиться с языком по умолчанию — он будет основным, а затем точечно добавить перевод под конкретный язык. Например, по умолчанию всегда будет английский, а для пользователей из России сделаем отдельный перевод. Чтобы задать язык, нужно передать двухбуквенный код страны.

👤 Название бота

Основной язык (метод setMyName):
— https://api.telegram.org/bot<TOKEN>/setMyName?name=<NAME_EN>

На русском:
— https://api.telegram.org/bot<TOKEN>/setMyName?name=<NAME_RU>&language_code=ru

Проверка (метод getMyName):
— https://api.telegram.org/bot<TOKEN>/getMyName
— https://api.telegram.org/bot<TOKEN>/getMyName?language_code=ru

🗓 Описание профиля бота

Основной язык (метод setMyShortDescription):
— https://api.telegram.org/bot<TOKEN>/setMyShortDescription?short_description=<SHORT_DESCRIPTION_EN>

На русском:
— https://api.telegram.org/bot<TOKEN>/setMyShortDescription?short_description=<SHORT_DESCRIPTION_RU>&language_code=ru

Проверка (метод getMyShortDescription):
— https://api.telegram.org/bot<TOKEN>/getMyShortDescription
— https://api.telegram.org/bot<TOKEN>/getMyShortDescription?language_code=ru

📝 Описание бота при открытии

Основной язык (метод setMyDescription):
— https://api.telegram.org/bot<TOKEN>/setMyDescription?description=<DESCRIPTION_EN>

На русском:
— https://api.telegram.org/bot<TOKEN>/setMyDescription?description=<DESCRIPTION_RU>&language_code=ru

Проверка (метод getMyDescription):
— https://api.telegram.org/bot<TOKEN>/getMyDescription
— https://api.telegram.org/bot<TOKEN>/getMyDescription?language_code=ru

📢 Команды в боте

Основной язык (метод setMyCommands):
— https://api.telegram.org/bot<TOKEN>/setMyCommands?commands=<COMMANDS_EN>

На русском:
— https://api.telegram.org/bot<TOKEN>/setMyCommands?commands=<COMMANDS_RU>&language_code=ru

Проверка (метод getMyCommands):
— https://api.telegram.org/bot<TOKEN>/getMyCommands
— https://api.telegram.org/bot<TOKEN>/getMyCommands?language_code=ru

🖼 Скриншоты в профиле бота

Тут попроще. Надо зайти в редактирование самого бота и в конце экрана загрузить скриншоты под каждый язык.

◀️ Кнопка меню мини-аппа

А тут чуть посложнее. Смысл в том, что когда пользователь стартует бота (вызывает команду /start), то в этот момент вместе с приветственным сообщением можно заодно изменить название кнопки, используя метод setChatMenuButton.

#инструкции

🛠 Включение режима отладки в мини-аппе

Разработка веб-приложения — дело непростое. Очень часто нам нужно проинспектировать элементы и отловить какое-то несоответствие или баг.

🖥 Telegram Desktop

— Через боковое меню перейдите в Настройки → Продвинутые настройки → Экспериментальные настройки и включите опцию Enable webview inspecting
— Запустите мини-апп и через правую кнопку мышки будет доступен веб-инспектор

🖥 Telegram для macOS

— Прямо на главном экране нажмите быстро 5 раз на иконку настроек и включите опцию Debug Web App
— Запустите мини-апп и через правую кнопку мышки будет доступен веб-инспектор

📞 Telegram для Android

— Через боковое меню перейдите в Настройки, в самом низу нажмите и удерживайте на номере версии, затем выберите Enable WebView Debug
— Включите отладку по USB на устройстве. Подключитесь к компьютеру через кабель, запустите мини-апп и выберите веб-инспектор через вкладку «Девайсы».

📞 Telegram для iOS и iPadOS

— Прямо на главном экране нажмите быстро 10 раз на иконку настроек и включите опцию Allow Web View Inspector
— Включите функции для веб-разработчиков в Сафари, а затем и на самом устройстве. Подключитесь к Маку через кабель, запустите мини-апп и откройте веб-инспектор через вкладку «Разработка».

#инструкции

🔍 Отключаем зум в веб-аппе

Периодически встречаю приложения, контент которых можно масштабировать жестами. Закрывать на это глаза, конечно же, не стоит, тем более, что исправляется такое поведение одной строчкой в html:

<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, user-scalable=no, shrink-to-fit=no">

#инструкции

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

#инструкции

💻 Определение устройства в мини-аппе

В АПИ мини-аппов есть параметр platform, который возвращает название платформы, на которой открыто приложение.

Так как официальных клиентов несколько, то вот что попадает в его значение:

— ios (Айфон и Айпад);
— macos (Мак);
— tdesktop (Мак и Винда);
— android (Андроид);
— weba (Веб А);
— web (Веб К);
— unknown (если не определено).

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

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

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

❓ Используете ли вы этот параметр? А для чего?)

#инструкции

🔒 Блокировка ориентации экрана

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

Для управления ориентацией в АПИ доступны два метода: lockOrientation() и unlockOrientation().

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

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

// Проверка поддержки ориентации в браузере
const isOrientationSupported = 'orientation' in screen;

// Блокировка и разблокировка ориентации
const lockOrientation = () => Telegram.WebApp.lockOrientation();
const unlockOrientation = () => Telegram.WebApp.unlockOrientation();

// Проверка текущей ориентации
const checkOrientation = () => {
  // Работа только с мобильными устройствами
  if (!['ios', 'android'].includes(Telegram.WebApp.platform)) {
    return false;
  }

  // Блокировка при портретной (вертикальной) ориентации
  if (screen.orientation.type.startsWith('portrait')) {
    lockOrientation();
  // Разблокировка при ландшафтной (горизонтальной) ориентации
  } else if (screen.orientation.type.startsWith('landscape')) {
    unlockOrientation();
  }
};

// Установка слушателей событий
const setupOrientationListeners = () => {
  if (!isOrientationSupported) {
    return false;
  }

  // Прослушка изменения ориентации в реальном времени
  window.addEventListener('orientationchange', checkOrientation);

  // Прослушка событий сворачивания и разворачивания приложения
  Telegram.WebApp.onEvent('activated', checkOrientation);
  Telegram.WebApp.onEvent('deactivated', unlockOrientation);
}

// Очистка слушателей событий
const cleanupOrientationListeners = () => {
  if (!isOrientationSupported) {
    return false;
  }

  // Отписка от слушателей изменения ориентации
  window.removeEventListener('orientationchange', checkOrientation);

  // Отписка от слушателей сворачивания и разворачивания
  Telegram.WebApp.offEvent('activated', checkOrientation);
  Telegram.WebApp.offEvent('deactivated', unlockOrientation);
};

// Инициализация
checkOrientation();
setupOrientationListeners();

// Очистка (при необходимости)
// cleanupOrientationListeners();

Потестировать можно в 🍅 Помидорке. Там я пошел чуть дальше и в горизонтальном виде дополнительно добавил иконку с текстом о необходимости поворота.

#инструкции