🪁 Запуск из любого чата

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

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

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 и вставлять ее где угодно.

———

🔄 Обновлено 09.05.25

С выходом версии 8.0 на телефонах такая кнопка теперь доступна по умолчанию через меню мини-аппа, там где три точки 💬

#инструкции

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

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

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

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

Почти все можно настроить обычными запросами с вызовом соответствующего метода через АПИ по адресу 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 (если не определено).

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

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

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

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

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

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

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

Для управления ориентацией в АПИ доступны два метода: 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();

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

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

✨ Анимированные эффекты при отправке сообщения

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

От имени бота так же можно добавлять такой эффект в некоторых методах, используя уникальный идентификатор в параметре message_effect_id, но их всего шесть:

🔥 — 5104841245755180586
👍 — 5107584321108051014
❤️ — 5159385139981059251
🎉 — 5046509860389126442
👎 — 5104858069142078462
💩 — 5046589136895476101

Спасибо @kulikov_aleks за наводку 👍

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

🌓 Светлая и темная темы

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

Чтобы мини-приложение поддерживало такое поведение, необходимо добавить метатег и CSS-свойство:

<meta name="color-scheme" content="light dark">

:root {
  color-scheme: light dark;
}

Работа метатега и CSS-свойства одинакова, однако метатег помогает немедленно загрузить необходимую тему, не дожидаясь загрузки CSS. Это позволяет избежать классической ситуации, когда при открытии приложения ночью экран сначала ослепляет белым светом, а затем переключается на темную тему 😵

В дополнение при запуске мини-приложения Телеграм предоставляет текущее значение цветовой схемы через CSS-переменную --tg-color-scheme. Она пригодится для разрешения конфликтов, когда, например, на уровне системы тема оформления светлая, а приложение Телеграма — темное.

В этом случае CSS можно переписать так:

:root {
  color-scheme: var(--tg-color-scheme, light dark);
}

Далее было бы удобно манипулировать стилями через медиавыражение prefers-color-scheme, но на практике оно работает некорректно в некоторых случаях, поэтому выходом послужит добавление дата-атрибута с названием темы к корневому элементу html и последующего ориентирования на него в CSS.

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

// Устанавливаем значение при запуске
document.documentElement.dataset.mode = Telegram.WebApp.colorScheme;

// Меняем его при переключении
Telegram.WebApp.onEvent('themeChanged', () => {
  document.documentElement.dataset.mode = this.colorScheme;
});

Теперь можно легко управлять стилями:

body {
  background-color: #fff;
  color: #000;
}

[data-mode="dark"] body {
  background-color: #000;
  color: #fff;
}

Итоговый пример кода:

<html>
  <head>
    <!-- … -->
    <meta name="color-scheme" content="light dark">
    <style>
      :root {
        color-scheme: var(--tg-color-scheme, light dark);
      }

      body {
        background-color: #fff;
        color: #000;
      }

      [data-mode="dark"] body {
        background-color: #000;
        color: #fff;
      }
    </style>
    <script>
      document.documentElement.dataset.mode = Telegram.WebApp.colorScheme;

      Telegram.WebApp.onEvent('themeChanged', () => {
        document.documentElement.dataset.mode = this.colorScheme;
      });
    </script>
    <!-- … -->
  </head>

  <body>
    <!-- … -->
  </body>
</html>

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

🆔 Идентификаторы

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

➡️ Telegram Desktop: Настройки ▶️ Продвинутые настройки ▶️ Экспериментальные настройки ▶️ опция Show Peer IDs in Profile ✅

➡️ Telegram для MacOS: Настройки ▶️ Общие ▶️ опция «Показывать ID чатов в профиле»  ✅

Стоит учесть, что в случае с группами и каналами к айдишнику в начале еще нужно приписать -100. То есть, если в профиле ID указан как 123456789, то итоговый ID будет -100123456789.

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

✨ Эффект блеска на кнопке

В документации, начиная с версии АПИ 7.10, есть вот такой прикольный эффект блеска главной и второстепенной кнопок для привлечения внимания.

Делается через параметр has_shine_effect в методе setParams:

// Главная кнопка
Telegram.WebApp.MainButton.setParams({
  has_shine_effect: true,
})

// Второстепенная кнопка
Telegram.WebApp.SecondaryButton.setParams({
  has_shine_effect: true,
})

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