Mini App в MAX — это веб-приложение, которое размещается по HTTPS и подключается к прошедшему модерацию чат-боту. Клиент открывает его внутри мессенджера, а приложение получает контекст запуска через MAX Bridge и взаимодействует с backend компании.
Для production-сценария недостаточно сверстать несколько экранов. Нужно безопасно проверить данные пользователя, вынести секреты на сервер, обработать состояния MAX и протестировать полный путь до CRM или другой системы.
Что потребуется
- верифицированный профиль организации, ИП или самозанятого;
- созданный и прошедший модерацию бот;
- frontend на HTML, CSS и JavaScript;
- HTTPS-хостинг;
- backend для бизнес-логики и интеграций;
- MAX Bridge;
- юридические документы для фактического сценария;
- тестовые данные и доступы.
Шаг 1. Создайте и промодерируйте бота
Mini App подключается к конкретному чат-боту. Сначала создайте его на платформе для партнёров, заполните карточку и дождитесь успешной модерации.
После проверки откроются токен и расширенные настройки. Токен нужен backend для API MAX, но не должен попадать в клиентское приложение.
Шаг 2. Спроектируйте сценарий
Определите:
- С какого сообщения или ссылки открывается приложение.
- Какой экран пользователь видит первым.
- Какие данные приходят из MAX.
- Какие данные запрашиваются у пользователя.
- Что проверяется на backend.
- Куда записывается результат.
- Как бот подтверждает действие.
Не начинайте архитектуру с набора страниц. Сначала опишите состояния бизнес-операции: черновик, проверка, подтверждение, ошибка, отмена и повтор.
Шаг 3. Создайте frontend
Mini App работает на стандартных веб-технологиях. Можно использовать React, Next.js или другой подходящий стек, если итоговая сборка доступна по HTTPS и корректно работает внутри webview MAX.
Интерфейс должен поддерживать:
- мобильную ширину от 375 px;
- светлую и тёмную тему, если данные темы передаются клиентом;
- безопасные зоны и экранную клавиатуру;
- возврат назад;
- загрузку и повтор;
- отсутствие данных;
- ошибки сети;
- закрытие и повторный запуск.
Для визуальной согласованности можно использовать библиотеку React-компонентов MAX UI.
Шаг 4. Подключите MAX Bridge
MAX Bridge предоставляет объект window.WebApp и методы взаимодействия с клиентом мессенджера. Через него приложение получает стартовые параметры и может использовать поддерживаемые возможности интерфейса.
Важно различать:
- initData — строку, которую нужно отправить на backend для проверки;
- initDataUnsafe — распарсенные значения для удобства интерфейса, которым нельзя безусловно доверять в операциях с данными.
Перед использованием конкретного метода сверяйтесь с актуальной документацией MAX Bridge.
Шаг 5. Валидируйте стартовые данные на сервере
Frontend отправляет initData своему backend. Сервер проверяет подпись и актуальность по официальному алгоритму, после чего создаёт собственную сессию.
Нельзя предоставлять доступ к заказам, документам или профилю только по user_id, пришедшему из браузера. Пользовательский клиент можно модифицировать.
Схема проверки опубликована в разделе валидации данных.
Шаг 6. Разместите приложение по HTTPS
Frontend должен быть доступен по валидному HTTPS-URL. Официальные требования к адресу:
- протокол https://;
- длина не более 1024 символов;
- валидный домен;
- отсутствие пробелов.
Для production используйте собственный контролируемый домен, мониторинг сертификата и процесс отката релиза. Статический хостинг подходит интерфейсу, но бизнес-операции всё равно выполняются backend.
Шаг 7. Подключите URL к боту
Откройте:
Чат-боты → Перейти → Расширенные настройки → Настроить.
Укажите URL Mini App и выберите вид кнопки: «Открыть», «Старт», «Играть» или вариант без подписи, если он подходит сценарию.
После сохранения кнопка появится в чате с ботом.
Шаг 8. Настройте диплинки
Диплинк открывает Mini App и передаёт параметр запуска:
https://max.ru/<botName>?startapp=<payload>Payload может содержать до 512 символов и использовать латинские буквы, цифры, _ и -. Его удобно применять для:
- источника кампании;
- конкретного товара;
- филиала;
- услуги;
- реферального кода;
- экрана или сценария.
Не передавайте в payload персональные данные и секреты. Рассматривайте параметр как подсказку, которую backend проверяет перед действием.
Шаг 9. Постройте backend
Backend выполняет:
- валидацию MAX initData;
- создание серверной сессии;
- хранение состояния;
- работу с токеном бота;
- интеграцию с CRM, 1С и другими API;
- расчёты и проверку цен;
- контроль прав;
- идемпотентность;
- логирование и мониторинг.
API frontend должен возвращать предсказуемые коды и сообщения, чтобы интерфейс мог корректно показать ошибку и предложить повтор.
Шаг 10. Подключите сообщения бота
После завершения действия backend отправляет пользователю сообщение через API MAX. Это может быть:
- номер заявки;
- подтверждение записи;
- состав заказа;
- ссылка на оплату;
- статус обращения;
- напоминание;
- кнопка повторного открытия Mini App.
Не отправляйте подтверждение, пока внешняя система не зафиксировала результат или пока не обозначено, что заявка ожидает проверки.
Шаг 11. Настройте аналитику
Передавайте:
- payload и источник;
- идентификатор сессии;
- открытие и закрытие;
- начало целевого действия;
- шаги формы;
- ошибки;
- успешную операцию на backend;
- идентификатор CRM или заказа;
- повторный визит.
Персональные данные не должны попадать в аналитические системы без необходимости и правового основания.
Шаг 12. Протестируйте внутри MAX
Обычный браузер не воспроизводит весь контекст webview. Проверяйте приложение в мобильных, desktop- и web-клиентах MAX, которые входят в целевую аудиторию.
Тест-кейсы:
- первый и повторный запуск;
- диплинк с валидным и неверным payload;
- истёкшие initData;
- медленная сеть;
- закрытие на середине;
- недоступный backend;
- повторная отправка;
- тёмная тема;
- экранная клавиатура;
- разные размеры;
- ошибка CRM или 1С.
Частые ошибки
- Подключать Mini App до готовности бота и модерации.
- Доверять initDataUnsafe на серверных операциях.
- Хранить токен бота во frontend.
- Не обрабатывать возврат и повторный запуск.
- Использовать HTTP вместо HTTPS.
- Передавать персональные данные в payload.
- Показывать устаревшие цены и статусы.
- Тестировать только в обычном браузере.
- Не настроить мониторинг backend.
Частые вопросы
Может ли Mini App работать без бота?
Нет. В текущей архитектуре MAX приложение подключается к прошедшему модерацию боту.
Можно ли использовать Next.js?
Да. Важно, чтобы клиентская часть корректно работала внутри webview, была доступна по HTTPS и не зависела от неподдерживаемых браузерных возможностей.
Обязателен ли MAX UI?
Нет, но библиотека помогает сделать интерфейс согласованным с мессенджером. Собственный дизайн должен оставаться удобным и учитывать паттерны MAX.
Где хранить пользовательские данные?
На контролируемом backend и в базе данных с необходимыми мерами защиты. Frontend не должен быть единственным хранилищем бизнес-состояния.
Как открыть конкретный экран из рекламы или канала?
Использовать диплинк с startapp и безопасно обработать payload на стороне приложения и backend.