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

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

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

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

Перед текстовой инструкцией рекомендуем посмотреть видео:

Создаём Мини-прилoжение в конструкторе чат-ботов для Telegram

Обновление Мини-прилoжений

Как создать мини-приложение в MAX для регистрации на мероприятие

Создание наполнения Мини-приложения и настройки

В разделе Конструктор создайте приложение или выберите существующее.

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

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

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

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

Блок Текст

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

Блок Видео

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

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

Для блока Видео есть дополнительные настройки, которые позволяют совершить действия при запуске видео, или после просмотра 95% видео.

Например вы хотите зафиксировать факт начала просмотра видео изменив переменную или категорию, или запустить сценария напоминания, если пользователь не перешел далее.

Настройка Изменить состояние Фиксированной кнопки позволяет активировать действие фиксированной клавиатуры после просмотра видео, например чтобы пользователь смог пройти дальше только после просмотра видео.

Блок Стикер

Блок Заголовок

Блок Описание

Блок Строки

В этом блоке вы можете создать ряды с информацией в формате Название: Значение
Для каждой строки можно загрузить иконку-изображение с разрешением 160x160.

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

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

Блок Вкладки

Вкладки работают по приницпу подстановки, в каждой вкладке вы можете указать название другого приложения, которое будет подставлено на странице при выборе вкладки. Этот блок отлично подходит для создания категорий товаров для Магазина, например вы можете создать вкладки "Обувь", "Одежда" для отображения страниц (приложений) с этими товарами.

Стандартные вкладки вмещают до 5 страниц,
Расширенные до 24 страниц + возможность загрузить иконку 160x160.

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

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

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

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

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

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

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

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

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

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

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

Форма ввода с типом Выбор валюты

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

Блок Карточки

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

Соотношение можно изменить на пиксели или проценты.
Если установлены проценты, то ширина или высота указывается в процентах относительно ширины или высоты приложения.
Условно если задать ширину карточки в 50%, то при растягивании приложения будет растягиваться и сама карточка, сохраняя ширину в 50%.

Если задать один параметр в точном значении, а другой в auto, то размер изображения изменится по заданным параметрам, не испортив пропорции.

• Карточка: Изображение или видео до 50 мб.
  Опционально можно добавить заголовок и описание, которые будут под карточкой.
• Действия карточки: Можно выбрать такие же действия как и для кнопок, или оставить без действия.
• Выполнить вибрацию: Настройка вибрации при нажатии
• Показать попап: Всплывающее окно с текстом после нажатия на карточку, можно добавить кнопку.
• Изменить Переменную: Возможность указать переменную для изменения после нажатия карточки.
• Закрыть Мини-приложение: Приложение будет закрыто после нажатия на карточку.
• Кнопка Скрыть карточку: При включении в углу карточки будет отображаться крестик для скрытия карточки. Доступно только для типа Прямоугольный
• Добавить бейдж: Возможность добавить выделяющийся текст в углу карточки, например "Акция", "Новое поступление", "Важно знать" и тд.
• Изменить прозрачность: Процент прозрачности карточки

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

Блок 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>

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>

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

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

Настройки

• Обернуть в блок: Добавляет отдельный выделяющийся фон для подставляемого блока
• Выделить блок: Доступно если выбрано Обернуть в блок. Для iOS отступы слева и справа от границ экрана будут убраны, а для Android добавлены, что визуально выделит блок на фоне других блоков.
• Скрыть под заголовок: Подставляемый контент будет скрыт под заголовок, на который нужно нажать чтобы раскрыть содержимое. Пример на скриншоте выше.

Блок Разделитель

Блок Баннер

Разберем настройки

• Расположение: Слева или По центру - это расположение всех элементов в баннере
• Загрузка файла: Изображение или видео для баннера до 10 мб.
• Адаптация темы: Если фон тёмный, то для элементов над фоном будет использоваться цвет от светлой темы и наоборот.
• Изменить фон: Позволяет задать свой цвет.
• Аватар: Опциональная возможность добавить аватар или логотип в виде круглого блока.
• Заголовок: Жирный текст до 320 символов с настройкой размера шрифта.
• Текст: Прописной текст 1024 символов с настройкой размера шрифта.
• Бейдж: Выделяющийся текст с отдельным цветовым фоном для акцентирования внимания. В текст бейджа можно поставить переменную, в таком случае бейдж будет отображаться, если в переменной есть какое-либо значение и не будет отображаться, если значения нет.
• Способ нажатия:
  Весь баннер — при такой настройке сам баннер служит в качестве кнопки и принимает нажатия в любом месте.
  Кнопка — возможность задать Обычную или Инлайн кнопку со своим действием.

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

• • Кнопка Скрыть баннер — крестик "×" в углу баннера, позволяет скрыть баннер. Важно! После закрытия пользователь не сможет снова увидеть этот баннер даже после перезапуска приложения.
  • Выделить блок — Для iOS отступы слева и справа от границ экрана будут убраны, а для Android добавлены, что визуально выделит баннеры на фоне других блоков. Пример на скриншоте ниже.
  • Добавить описание — позволяет добавить полупрозрачный текст внизу блока.

Блок Меню

Настройки

• Стиль: выбор варианта кнопок, иконка с текстом или только иконка.
• Изображение: загрузка иконки в формате SVG изображения.
• Название кнопки: Текст под иконкой кнопки.
• Действие кнопки: Выбор действия, в этом случае переход к другому Мини-приложению
• Активные страницы: Укажите Мини-приложения, на которых кнопка будет находится в активном состоянии. Это нужно, если клавиатуру вы создали в одном приложении, и далее через блок Подстановка указали его в других приложения для дублирования клавиатуры, и для каждой кнопки нужно указать, на каких страницах (приложениях) кнопка будет подсвечена как выбранная (активная).
• Выполнить вибрацию: Настройка силы и типа вибрации при нажатии.
• Показать попап: Всплывающее текстовое окно.

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

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

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

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

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

Блок Товар

Для создания товаров используйте Магазин, подробнее: Обзор раздела Магазин

Блок Поиск

Настройки

• Названия мини-приложений: Здесь вы указываете, какие именно приложения или группы команд буду индексироваться в поиске. Например у вас есть приложение для администрации, и вы не хотите чтобы его содержимое можно было найти через поиск. Укажите только необходимые.
• Элементы поиска: Выберите, какие блоки в приложении будут индексироваться в поиске. Например вы хотите чтобы поиск был только по текстовым блокам.
• Отображение: Укажите что должно отображаться в найденном блоке.

Поисковые настройки приложения

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

Попап

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

Вкладка Настройки

Ссылки

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

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

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

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

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

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

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

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

• Закрывать окно по жесту (свайп) вниз — Telegram может неверно реагировать на быструю прокрутку страницы и закрывать окно Мини-приложения когда это не нужно, вы можете отключить функцию и закрытие окна будет происходить при клике на кнопку “Закрыть”.
• Задать цвет шапки — здесь вы можете задать цвет для верхней части приложения.
• Задать фон — здесь вы можете задать отдельный фоновый цвет для приложения.
  Цвет шапки и фон применится индивидуально только к выбранному приложению. Общие настройки цвета фона и шапки для всех приложений (или страниц) находятся в разделе Настройки (бота) → Мини приложения → Внешний вид.
• HTML код — Возможность вставить HTML код в текущую страницу приложения между тегами <head>...</head>.

Вкладка Дeйствия

Список довольно обширен и содержит все необходимые действия такие как запись в таблицу или изменение переменных и категорий, API запросы к внешним сервисам и многое другое.

Общие настройки и внешний вид

Настройки

• Ссылки на главное Мини-приложение
• Открывать на полный экран: Мини-приложение будет открыто без “Шапки” где отображается название бота. Доступно только для Telegram.
• Кнопка "Настройки": Добавление нативной Telegram кнопки Настройки в углу приложения.

• HTML код: Возможность добавить общий HTML код, который будет подставлен между тегами <head>...</head> на всех страницах Мини-приложений.
• Жест "Назад": Включение функции позволяет выполнять действие "Назад" свайпом слева направо.

Внешний вид

Здесь вы можете задать собственные настройки цвета шапки и фона для разных тем, а так же указать стиль iOS или Android.

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

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

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

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

Другое

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