Мини-приложение MAX на MAX Bridge: быстрый старт

Обновлено 20 октября 2026 г.3 мин

Мини-приложение в MAX — это обычная веб-страница на HTML, CSS и JavaScript, которая открывается внутри мессенджера из чата с ботом. Все требования и названия методов ниже взяты из документации dev.max.ru.

1. Что нужно заранее

Бот на платформе MAX для партнёров. Мини-приложение привязывается к боту, поэтому сначала нужен верифицированный профиль и бот: первый чат-бот через API.
Хостинг с https. Подойдёт VK Cloud, GitHub Pages, Yandex Cloud или любой другой (dev.max.ru).

2. Подключите приложение к боту

На платформе для партнёров откройте Чат-боты и выберите бота.
Нажмите ⋮ → Настройки.
Вставьте URL мини-приложения.
Выберите вид кнопки — Открыть, Старт, Играть или без названия — и нажмите Сохранить.

Требования к URL: только https://, не длиннее 1024 символов, без пробелов, в адресе только латиница, цифры, точка и дефис. После сохранения в чате с ботом появится кнопка запуска. Подробнее: подключение мини-приложения, смена кнопки.

3. Подключите MAX Bridge

<script src="https://st.max.ru/js/max-web-app.js"></script>
<script>
  const app = window.WebApp;
  const user = app.initDataUnsafe.user;            // только для показа в интерфейсе
  document.body.textContent = `Привет, ${user?.first_name ?? 'гость'}!`;
</script>

После подключения библиотеки появляется глобальный объект window.WebApp. Отдельно инициализировать его не нужно (dev.max.ru: MAX Bridge). Часто нужны такие методы:

initData и initDataUnsafe — стартовые данные: пользователь, чат, auth_date, query_id;
platform, version — где и в какой версии MAX открыто приложение;
BackButton.show() / onClick() — системная кнопка «Назад»;
enableClosingConfirmation() — предупреждение о потере введённых данных при закрытии;
openLink(url) открывает внешний браузер (только после клика пользователя), openMaxLink(url) — ссылки max.ru внутри MAX;
HapticFeedback — вибрация при нажатиях.

4. Стартовые параметры через диплинк

Ссылка https://max.ru/<имя_бота>?startapp=<payload> открывает мини-приложение сразу, без запуска бота. В payload — до 512 символов: латиница, цифры, _ и -. Если параметр длиннее или содержит другие символы, он удаляется. В приложении значение доступно в window.WebApp.initDataUnsafe.start_param (dev.max.ru).

Не передавайте в payload персональные данные в открытом виде — используйте одноразовые токены. Подробнее: диплинк для мини-приложения.

5. Проверяйте initData на сервере

initDataUnsafe нельзя использовать для авторизации. Отправьте на сервер строку initData и проверьте подпись (dev.max.ru: валидация):

Разберите initData на пары key=value. Достаньте hash и уберите его из набора.
URL-декодируйте значения, отсортируйте пары по ключу (a → z) и соедините через \n — получится launch_params.
secret_key = HMAC_SHA256("WebAppData", BOT_TOKEN).
Сравните hex(HMAC_SHA256(secret_key, launch_params)) с hash. Если совпадает — данные подлинные.

Заодно проверьте auth_date (Unix-время в секундах), чтобы не принимать старые данные.

6. Номер телефона

window.WebApp.requestContact() показывает нативное окно MAX и возвращает phone, authDate и hash (dev.max.ru: MAX Bridge):

Номер подтверждают сравнением hash с HMAC_SHA256 от строк authDate, phone и userId (пары key=value по алфавиту через \n), где ключ — токен бота. Номер — без +.
Если пользователь отказался, придёт ошибка client.request_phone.user_refused_provide_phone_number.
Номер можно использовать только для работы этого мини-приложения.

Если не работает

Кнопки запуска нет в чате — проверьте, что URL сохранён в настройках бота и начинается с https://.
window.WebApp не определён — страница открыта в обычном браузере, а не внутри MAX, или скрипт max-web-app.js не загрузился.
Нужно обновить код — опубликованное приложение можно менять: обновление мини-приложения.
Модерация и контент — ограничения на контент.

Недавние запросы

Часто ищут

Разделы