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

Чтобы создать мини-приложение в MAX, сначала нужен верифицированный профиль на платформе для партнёров и промодерированный чат-бот. Затем вы разрабатываете обычное веб-приложение на HTML, CSS и JavaScript, подключаете MAX Bridge, размещаете проект по постоянному HTTPS-адресу и указываете этот URL в расширенных настройках бота.

Подключить Mini App без чат-бота нельзя: бот хранит ссылку и служит точкой запуска. Frontend взаимодействует с клиентом MAX через MAX Bridge, а серверная часть при необходимости обращается к Bot API. Инструкция проверена 7 сентября 2026 года. Если вам нужно не разрабатывать сервис, а понять, что это за формат и почему он не открывается, сначала прочитайте обзор мини-приложений в MAX.

Что такое Mini App и чем оно отличается от бота

Mini App — это веб-интерфейс, который открывается внутри мессенджера MAX. В нём можно показать каталог, форму записи, личный кабинет, игру, оплату или другой сценарий, для которого одних текстовых команд и кнопок чат-бота недостаточно.

Бот отвечает за вход в сценарий, сообщения и работу с Bot API. Мини-приложение отвечает за экраны и действия пользователя. Обычно frontend показывает интерфейс, backend хранит данные и выполняет бизнес-логику, а MAX Bridge связывает веб-приложение с клиентом MAX.

Не нужно превращать Mini App в копию большого сайта. Лучше выбрать одну задачу: оформить заказ, записаться, посмотреть статус или заполнить анкету. Чем короче путь от кнопки запуска до результата, тем проще приложение тестировать и поддерживать.

Что потребуется до начала разработки

• Профиль на платформе MAX для партнёров. По действующим правилам подключаться могут организации, ИП и самозанятые — резиденты России. Обычное физическое лицо без такого статуса пройти верификацию пока не может.
• Чат-бот. Его нужно создать, заполнить карточку и отправить на модерацию. Полный процесс разобран в инструкции как создать бота в MAX.
• Веб-приложение. Подойдёт frontend на обычных HTML, CSS и JavaScript или на привычном фреймворке. Backend нужен, если сервис хранит данные, принимает заказы, обращается к базе или проверяет пользователя.
• Публичный HTTPS-адрес. Локальный адрес разработчика для подключения не подходит. Нужен валидный URL без пробелов, доступный из приложения MAX.
• Тестовые устройства. Проверьте работу как минимум на Android, iOS и в веб-версии. Если аудитория пользуется настольным клиентом, добавьте desktop в матрицу проверки.

Какой способ создания выбрать

Конструктор не отменяет требований MAX: всё равно понадобятся бот, корректный HTTPS-адрес, проверка пользовательского пути и соблюдение правил платформы. Выбирая сервис, заранее выясните, кому принадлежат домен, код и данные, можно ли выгрузить проект и сколько стоит поддержка после запуска.

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

Шаг 1. Создайте и промодерируйте бота

Зарегистрируйте профиль организации, ИП или самозанятого, пройдите верификацию и создайте чат-бота на платформе для партнёров. Подготовьте понятные имя, описание и изображение. Подключать Mini App следует после того, как бот прошёл модерацию.

Если мини-приложение создаётся для компании, полезно заранее разобраться с возможностями MAX для бизнеса: доступами, ответственными сотрудниками и тем, какие данные действительно нужны сервису.

Шаг 2. Спроектируйте сценарий и экраны

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

Для магазина это может быть цепочка «каталог → карточка товара → корзина → заказ». Сам сценарий продаж подробно описан в статье про магазин в MAX; здесь важен именно технический путь создания Mini App.

Шаг 3. Разработайте frontend

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

Для React-проекта можно использовать библиотеку компонентов MAX UI. Она помогает приблизить интерфейс к дизайн-системе MAX и адаптировать элементы под разные платформы. Это необязательное условие: приложение может работать и на другом стеке, если соблюдены требования к запуску и интерфейсу.

Шаг 4. Подключите MAX Bridge

Официальная библиотека MAX Bridge загружается с CDN и создаёт глобальный объект window.WebApp. Через него Mini App получает данные запуска, сведения о платформе и версии клиента, управляет кнопкой «Назад», открывает ссылки и вызывает поддерживаемые функции MAX.

<script src="https://st.max.ru/js/max-web-app.js"></script>
const app = window.WebApp;
const platform = app.platform;
const version = app.version;

Подключайте библиотеку до кода, который обращается к window.WebApp. При обычном открытии страницы во внешнем браузере объекта может не быть, поэтому предусмотрите понятное сообщение и безопасную обработку такого состояния.

Шаг 5. Добавьте backend и проверьте стартовые данные

window.WebApp.initData содержит строку стартовых параметров. Её нужно отправить на backend и проверить подпись по официальному алгоритму HMAC-SHA256 с использованием токена бота. Токен хранится только на сервере и никогда не попадает во frontend, репозиторий или публичный JavaScript.

initDataUnsafe удобен для отображения имени, языка и другого контекста, но эти данные нельзя считать подтверждёнными. Авторизацию, доступ к заказам, балансу или профилю разрешайте только после серверной проверки initData. Проверяйте также время auth_date; в документации MAX рекомендован интервал валидности около одного часа.

Шаг 6. Разместите приложение по HTTPS

Опубликуйте frontend и backend на рабочем домене. URL мини-приложения должен начинаться с https://, быть валидным, не содержать пробелов и укладываться в 1024 символа. Лучше сразу выбрать постоянный адрес, например https://app.example.ru/.

Если URL остаётся прежним, обновления можно выкладывать на сервер без повторной настройки ссылки: пользователь при следующем запуске увидит новую версию. При смене адреса его придётся обновить в панели управления ботом.

Шаг 7. Укажите URL в настройках бота

1. Откройте профиль на платформе MAX для партнёров.
2. Перейдите в раздел «Чат-боты» и выберите нужного бота.
3. Откройте «Расширенные настройки» → «Настроить».
4. Вставьте URL мини-приложения в поле ссылки.
5. Выберите подпись кнопки: «Открыть», «Старт», «Играть» или вариант без названия.
6. Сохраните настройки и запустите бота из обычного аккаунта MAX.

Шаг 8. Настройте запуск и диплинки

Прямая ссылка на опубликованное мини-приложение имеет вид https://max.ru/<botName>?startapp. После startapp можно передать параметр, например источник перехода или идентификатор сценария:

https://max.ru/MyShopBot?startapp=product_125

Для payload разрешены латинские буквы, цифры, подчёркивание и дефис; максимальная длина — 512 символов. Значение приходит в start_param. Не передавайте в нём токены, персональные данные и другую секретную информацию: используйте короткий идентификатор, который backend сопоставит с нужным сценарием.

Как протестировать Mini App

• Откройте приложение кнопкой бота и прямым диплинком.
• Проверьте первый запуск, повторное открытие и возврат на предыдущий экран.
• Сравните светлую и тёмную темы, Android, iOS, web и нужные desktop-клиенты.
• Отключите сеть во время отправки формы и убедитесь, что данные не теряются молча.
• Проверьте истёкшие и подменённые стартовые данные: backend должен отказать в доступе.
• Испытайте длинные имена, пустые ответы, повторное нажатие кнопки и медленную загрузку.
• Убедитесь, что внешние ссылки открываются ожидаемым способом, а внутренние ссылки MAX не выбрасывают пользователя в браузер без необходимости.

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

Частые ошибки и способы исправления

Mini App не открывается. Проверьте HTTPS, доступность адреса без авторизации на уровне сервера, отсутствие пробелов в URL и правильность ссылки в настройках выбранного бота.

window.WebApp не определён. Убедитесь, что MAX Bridge загружен раньше вашего кода и тест идёт внутри MAX. Для внешнего браузера добавьте безопасный запасной экран.

Пользователь считается авторизованным без проверки. Не доверяйте initDataUnsafe. Отправляйте исходную строку initData на backend и проверяйте её подпись и время выдачи.

Токен бота виден в коде страницы. Немедленно перевыпустите токен и перенесите все операции с ним на сервер. Секрет нельзя хранить во frontend или передавать пользователю.

Диплинк открывает не тот экран. Проверьте botName, написание startapp, допустимые символы и длину payload. Логику перехода стройте по короткому идентификатору, а не по непроверенному тексту из URL.

Приложение выглядит как уменьшенный сайт. Сократите навигацию, оставьте одну главную задачу на экран и проверьте размеры элементов на телефоне. Mini App должен помогать выполнить действие, а не переносить внутрь мессенджера весь корпоративный портал.

Чек-лист перед публикацией

• Профиль верифицирован, бот создан и прошёл модерацию.
• Приложение решает один понятный пользовательский сценарий.
• Frontend адаптирован к мобильному экрану и разным темам.
• MAX Bridge подключён до обращения к window.WebApp.
• initData проверяется на backend, токен бота не раскрывается.
• Рабочий URL использует HTTPS и не меняется при обычном обновлении проекта.
• Ссылка добавлена к правильному боту, кнопка запуска понятна пользователю.
• Диплинки, payload, ошибки сети и повторный запуск проверены на целевых устройствах.
• Содержание приложения соответствует правилам платформы MAX.

После запуска следите не только за открытиями, но и за завершением целевого действия: отправкой формы, оформлением заказа или получением результата. Если пользователи часто закрывают Mini App на одном экране, сначала исправьте этот шаг, а уже затем расширяйте функции.