Мини-приложения

В статье рассмотрим как создать и настроить Мини-приложение в Telegram боте.

Статьи на схожую тему:

1. Подключение мини-приложения для кнопки в боте (веб-бот).
2. Магазин в виде мини-приложения (веб-бота).

Мини-приложение — элемент Telegram, который фактически является веб-страницей открывающейся внутри Telegram и использующий расширенные возможности Mini App Api. Все мини-приложения интегрированы в ботов. Дизайн Мини-приложений адаптирован под стилистику iOS и Android.

Настройка Мини-приложения в BotFather

Через @BotFather можно включить специальный режим для запуска Мини-приложения по кнопке из профиля бота или по Стартовой ссылке https://t.me/username_bot?startapp, а также можно создать Короткие ссылки по типу https://t.me/username_bot/miniapp, рассмотрим оба варианта.

Кнопка "Открыть приложение" и Стартовая ссылка

Кнопка для открытия приложения из профиля бота.

Для включения режима Мини-приложения необходимо:

1. Перейти в @BotFather
2. Ввести /mybots и выбрать нужного бота
3. Открыть Bot Settings и выбрать Configure Mini App
4. Нажать Enable Mini App
5. Последним шагом необходимо открыть: Личный кабинет — Конструктор — выбрать уже созданное и опубликованное Мини-приложение — Скопировать Техническую ссылку и отправить её в @BotFather

Отлично, теперь Мини-приложение можно открыть по кнопке в профиле Telegram бота, а также по ссылке в виде https://t.me/username_bot?startapp, где на месте username_bot нужно подставить юзернейм вашего бота.

Короткая ссылка на Мини-приложение

Пример короткой ссылки на Мини-приложение.

Для создания короткой ссылки на Мини-приложение нужно: 

1. Перейти в @BotFather
2. Ввести /newapp 
3. Выбрать нужного бота и следовать дальнейшим шагам: Ввести название Мини-приложения — Описание — Отправить картинку (например из Yandex)— Прислать GIF или отправить /empty 
4. На шаге с отправкой ссылкой необходимо открыть: Личный кабинет — Конструктор — выбрать уже созданное и опубликованное Мини-приложение — Скопировать Техническую ссылку и отправить её в @BotFather
5. Последним шагом нужно задать окончание ссылки, например "price"

Настройки Мини-приложения в Конструкторе

Типы ссылок на Мини-приложение

В контексте личного кабинета существует всего 2 типа ссылок на Мини-приложения:

1. Прямая ссылка — имеет вид https://t.me/username_bot?startapp=10e220a237218f61, на конце ссылки указан ID необходимого Мини-приложения. 
   Область применения: можно вставлять в текст, в кнопки и в любые иные места для вызова Мини-приложения. 
   
   Важно! Для её использования необходимо в @BotFather включить режим Mini App, о котором написали выше.
    
2. Техническая ссылка — имеет вид https://cp.puzzlebot.top/web_page/test.html?id=10e220a237218f61 , на конце ссылки указан ID необходимого Мини-приложения. 
   Область применения: предназначена исключительно для настройки режима Mini App и для создания коротких ссылок в @BotFather. 
   
   По ней нельзя переходить и её нельзя вставлять в виде ссылки в текст.

Важно! Наблюдаются проблемы в работе Прямых ссылок со стороны Telegram клиентов, описали метод исправления ошибки.

 

Также, помимо Прямой ссылки для перехода к Мини-приложению есть ещё Короткая ссылка в виде https://t.me/username_bot/miniapp и Стартовая ссылка для открытия главной страницы Мини-приложения https://t.me/username_bot?startapp , о которых рассказали выше.

Дополнительные настройки

• Защита контента — функция запрещает копировать текст и отключает работу правой кнопки мыши.
• Отобразить кнопку "Назад" — кнопка отображается в левом верхнем углу окна мини-приложения, вместо кнопки “Закрыть”. Для неё можно выбрать следующие действия: Предыдущее мини-приложение, Переход к Мини-приложению, Переход к команде или условию.

Пример попапа перед закрытием Мини-приложения.

• Показать попап перед закрытием Мини-приложения — при закрытии Мини-приложения появится попап с предупреждением “Внесённые изменения могут быть потеряны”. Будет всегда отображаться для Мини-приложений с формами ввода.
• Закрывать окно по жесту (свайп) вниз — Telegram может неверно реагировать на быструю прокрутку страницы и закрывать окно Мини-приложения когда это не нужно, вы можете отключить функцию и закрытие окна будет происходить при клике на кнопку “Закрыть”.

Особенности блоков Мини-приложения

Для блоков можно добавить заголовок и описание.

Рассмотрим особенности настройки части блоков.

Блок Изображение

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

Блок Стикер

Может отображать анимацию в формате .TGS (формат Telegram стикеров) или JSON.

Блок Видео

Отображает видео загруженное на следующие платформы: YouTube, Vimeo, VK, Dzen, RuTube, OK. В блоке необходимо указать ссылку на видео из адресной строки. 

Для платформы Dzen необходимо скопировать особую ссылку. Чтобы её найти необходимо нажать под видео на три точки — Поделиться — Встроить.

Блок Клавиатура

В отличии от клавиатуры в боте — в Мини-приложении клавиатура может существовать отдельно от блоков. Клавиатур может быть любое количество, кроме клавиатуры с типом Фиксированная.

Для каждой кнопки можно настроить выполнение вибрации.

Тип клавиатуры: Фиксированная. Может быть только одна на всё Мини-приложение.

Важно! Фиксированная клавиатура может быть заменена, если внутри Мини-приложения есть Форма ввода. 
 

Тип клавиатуры: Обычная.

Тип клавиатуры: Строки.

Тип клавиатуры: Инлайн.

Блок Строки

Блок Документ

Блок позволяет скачать отдельные документы или все разом. Документы отправляются в личные сообщения с ботом.

Блок Форма ввода

Подробнее о Формах ввода рассказали в статье: Форма ввода. В данном разделе рассмотрим особенности Форм ввода в Мини-приложении.

Важно! При использовании Формы ввода в Мини-приложение автоматически добавляется блок Клавиатуры с типом Фиксированная. Если в Мини-приложении уже есть блок Клавиатуры с типом Фиксированная, то он будет заменён.
 

Для Форм ввода в Мини-приложении добавлены следующие функции:

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

У Формы ввода с типом Выбор варианта для кнопок есть настройка Выбрать по умолчанию, которая позволяет предустановить популярные варианты ответа.

При ответе на Формы ввода воспроизводится эффект конфетти.

Блок Форма ввода с типом Список

Данный тип формы ввода позволяет выбрать один или несколько вариантов из списка. Особенность типа в наличии поиска по  вариантам (в случае, если вариантов больше 10). Также данный тип предусматривает 3 способа добавления вариантов:

1. Через личный кабинет — до 16 вариантов
2. Текстовым документом — необходимо подготовить обычный .txt файл с содержимым по примеру:
   Название варианта 1 = Значение 1
   Название варианта 2 = Значение 2
   ...
   Название варианта N = Значение N

3. Подключением к Google Sheets или NocoDB Таблицам

Блок Подстановка

Блок позволяет подставить контент другого Мини-приложения. 

Важно! Действия другого Мини-приложения не будет выполнены.
 

Попап

Попапы могут быть 2 видов: С кнопкой и Без кнопки.

Блок Меню

Блок Меню позволяет загрузить SVG изображения в качестве иконок.

Блок Вкладки

Стандартные вкладки вмещают до 5 страниц, Расширенные до 24 страниц.

Блок HTML

Позволяет вставить HTML код между тегами <body></body>. 

Важно! В дополнительных настройках Мини-приложения, а также в глобальных настройках бота можно задать HTML код, который будет вписан между тегами <head></head>. 
 

Полезная информация: 

1. Классы .block-ios и .block-android — специальные классы для CSS кода для отображения элемента только для пользователей с iOS или Android соответственно, пример: 
   <div class="block_ios">У вас iOS тема</div>
   <div class="block_android">У вас Android тема</div>

2. Атрибут goto_web_page для тега <a> — переход от одного Мини-приложения к другому и без открытия нового окна. В него пишется ID Мини-приложения (например: bb0ad173446c99b1), после загрузки страницы этот атрибут заменяется на href с необходимым URL-адресом страницы, пример:

<a goto_web_page="*тут айди второй страницы*">Перейти на вторую страницу</a>

Обведённый код является ID Мини-приложения.

3. Функция gotoWebPage("id_Мини-приложения", true | false) — переходом от одного Мини-приложения к другому. Аналог предыдущего варианта. Второй аргумент необязательный и по умолчанию false. Если false, то сделает переход на указанное Мини-приложение в текущем окне, если true, то откроет в новом окне.

<button onclick="gotoWebPage('*тут айди второй страницы*')">Перейти на другую страницу</button>

4. Функция getWebPageUrl("id_Мини-приложения") — возвращает ссылку правильного вида, без перехода, пример:

<script>
var other_page_url = getWebPageUrl("bb0ad173446c99b1")
setTimeout(function() {
window.location.href = other_page_url;//этот пример выдуман, тут можно было обойтись gotoWebPage
}, 3000);//переход через 3 сек
</script>

Другое

1. Для действия в кнопках Подставить текст необходимо включить Инлайн-мод, подробнее: Инлайн-мод для инлайн-команд и групп команд в Конструкторе.
2. Вы можете интегрировать в Мини-приложение свой сайт, подробнее: Подключение мини-приложения для кнопки в боте (веб-бот).