Мини-приложения в MAX: как устроены и чем отличаются от Telegram Mini Apps

Мини-приложение в MAX — обычная веб-страница на HTTPS, которую открывает бот. Ниже — как его подключить, чем MAX Bridge отличается от Telegram.WebApp и что можно переиспользовать, если уже есть Mini App в Telegram. Факты сверены с документацией на 6 ноября 2026 года.

Содержание
  1. Что такое мини-приложение в MAX
  2. Как подключить
  3. Как открыть: кнопка настроек, open_app и диплинк
  4. MAX Bridge: объект window.WebApp
  5. Проверка initData на сервере
  6. Чем MAX отличается от Telegram Mini Apps
  7. Что переносится, если Mini App уже есть в Telegram
  8. Для каких задач это подходит
  9. С чего начать

В Telegram Mini App уже привычный инструмент: каталог, запись, калькулятор — всё внутри чата. В MAX схема похожая, но не копия. Приложение живёт только вместе с ботом, подключается через платформу для партнёров, а клиентский объект называется window.WebApp, а не window.Telegram.WebApp.

Я опираюсь на документацию MAX по мини-приложениям, MAX Bridge, валидацию данных и Telegram Mini Apps. Отдельно — на демо «Зерно и Пар»: Telegram Mini App кофейни лежит на tsemeneev.ru/coffee-app, бэкенд общий, и тот же интерфейс можно открыть в браузере.

Что такое мини-приложение в MAX

Это HTML, CSS и JavaScript на вашем хостинге. Пользователь нажимает кнопку в чате с ботом — и страница открывается внутри клиента MAX. Отдельного магазина приложений нет: URL вы сами указываете в настройках бота.

По FAQ MAX мини-приложение без чат-бота подключить нельзя. Через бота оно ходит в Bot API, получает пользователя и шлёт уведомления. Автономного «просто веб-приложения в MAX» нет.

Подключение доступно юрлицам, ИП и самозанятым — резидентам РФ. Это то же ограничение, что и для ботов на платформе партнёров. Подробности про регистрацию и модерацию — в статье «Бот в MAX для бизнеса».

Как подключить

  1. Выложите файлы на хостинг с HTTPS. В документации упоминают VK Cloud, GitHub Pages, Yandex Cloud; для продакшена подойдёт любой нормальный хост с сертификатом.
  2. Откройте платформу MAX для партнёров → Чат-боты → нужный бот → «Настройки».
  3. Вставьте URL мини-приложения и выберите подпись кнопки: «Открыть», «Старт», «Играть» или без названия.
  4. Сохраните. В чате с ботом появится кнопка запуска.

Требования к URL из документации:

  • длина не больше 1024 символов;
  • только https://;
  • допустимы латиница, цифры, точка и дефис;
  • пробелы запрещены.

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

Одновременно два мини-приложения открыть нельзя: новое закрывает текущее. В FAQ MAX написано, что поддержку нескольких окон сразу ещё делают.

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

Вторую точку входа даёт кнопка типа open_app в inline_keyboard. Её кладут под сообщением — например, «Открыть каталог» в приветствии. В справке по клавиатуре у open_app лимит как у ссылок: не больше трёх таких кнопок в одном ряду. В поле web_app передают HTTPS-адрес мини-приложения.

Третий способ — диплинк:

https://max.ru/<имя_бота>?startapp=<payload>

payload опционален, до 512 символов. Разрешены только A–Z, a–z, 0–9, _ и -. Если превысить лимит или вставить недопустимый символ, платформа вырежет payload из ответа. Значение приходит в initDataUnsafe.start_param и в сырой строке initData.

Типичные сценарии из документации MAX: QR на столике с startapp=feedback_rest123, промокод promo123, метка источника your_site, номер заказа order_12345. В payload не кладут телефон и пароль открытым текстом — только одноразовый токен или закодированный идентификатор сессии.

Для сравнения: в Telegram точек входа больше. Там есть кнопка меню, inline-кнопка, главное мини-приложение в профиле бота, прямая ссылка https://t.me/бот/приложение, inline-режим и меню вложений. В MAX набор короче: настройки бота, open_app и ?startapp=.

MAX Bridge: объект window.WebApp

Скрипт подключают с CDN:

<script src="https://st.max.ru/js/max-web-app.js"></script>

После загрузки доступен window.WebApp. Отдельный ready() в духе Telegram документация не требует: объект создаётся при запуске, данные уже предзагружены.

Что есть из коробки (по описанию Bridge):

  • initData — сырая строка для проверки на сервере;
  • initDataUnsafe — тот же набор уже разобранный в JSON (для UI, не для доверия);
  • platform — ios, android, desktop, web;
  • version и deviceName;
  • BackButton — кнопка «Назад» в шапке;
  • HapticFeedback — вибрация (impactOccurred, notificationOccurred, selectionChanged);
  • requestContact() — запрос номера с отдельной проверкой HMAC;
  • enableClosingConfirmation / disableClosingConfirmation;
  • openLink (внешний браузер) и openMaxLink (диплинк внутри MAX);
  • downloadFile(url, file_name) — скачивание только по HTTPS и только после клика пользователя; обычный <a href> в Bridge не используют;
  • shareContent / shareMaxContent — шеринг наружу или внутрь MAX;
  • openCodeReader — QR с камеры или из файла;
  • DeviceStorage и SecureStorage (во втором — до 10 ключей на пользователя; в вебе эти хранилища не работают);
  • BiometricManager — отпечаток или лицо (не на десктопе и не в вебе);
  • PermissionsManager — камера и микрофон (на момент документации — Android и веб, с оговоркой следить за обновлениями);
  • NfcManager — только Android.

Для визуальной части MAX отдаёт библиотеку React-компонентов MAX UI и гайдлайн в .fig. Это не обязательный стек: подойдёт и чистый JS, и Vue, и Svelte. UI-кит просто быстрее приводит интерфейс к привычному виду клиента MAX.

Чего в Bridge нет в том виде, к которому привыкли в Telegram: отдельной MainButton / SecondaryButton внизу экрана, CloudStorage на 1024 ключа, openInvoice и оплаты Stars, shareToStory, акселерометра и гироскопа. Если ваш Telegram Mini App завязан на нижнюю кнопку «Оформить» и счёт через openInvoice, в MAX эти куски придётся заменить своим UI и ссылкой на платёжную страницу провайдера. Про отсутствие платежей в MAX Bot API я уже писал в статье про перенос бота.

Проверка initData на сервере

Правило то же, что в Telegram: браузеру нельзя доверять. Пользователь может подменить user.id в DevTools. Сервер обязан проверить подпись строки initData (или параметра WebAppData из URL-фрагмента).

Алгоритм из документации MAX:

  1. Разобрать пары key=value, сохранить hash, остальные поля URL-декодировать.
  2. Отсортировать ключи по алфавиту и склеить через перевод строки: key1=value1\nkey2=value2.
  3. Получить секрет: HMAC-SHA256 от токена бота с ключом WebAppData.
  4. Подписать строку этим секретом, сравнить hex с пришедшим hash.
  5. Отбросить данные старше часа по auth_date — такой интервал рекомендует сама документация.

На Python проверка почти один в один совпадает с Telegram:

import hmac, hashlib, time
from urllib.parse import parse_qsl
from operator import itemgetter

def check_max_init_data(init_data: str, bot_token: str, max_age: int = 3600) -> dict | None:
    params = list(dict(parse_qsl(init_data, keep_blank_values=True)).items())
    received = next((v for k, v in params if k == "hash"), None)
    if not received:
        return None
    to_sign = sorted([(k, v) for k, v in params if k != "hash"], key=itemgetter(0))
    data_check = "\n".join(f"{k}={v}" for k, v in to_sign)
    secret = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
    calc = hmac.new(secret, data_check.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(calc, received):
        return None
    fields = dict(to_sign)
    if time.time() - int(fields.get("auth_date", 0)) > max_age:
        return None
    return fields

initDataUnsafe для этой проверки не годится — только сырая строка. Цену заказа, как и в Telegram-версии, считает сервер по своему прайсу: фронт присылает состав корзины, а не сумму.

Чем MAX отличается от Telegram Mini Apps

Тема MAX Telegram
Кто может подключить Юрлицо, ИП, самозанятый (РФ), бот на платформе партнёров Любой аккаунт через BotFather
Где живёт приложение Только внутри бота Бот, главное Mini App, прямые ссылки, inline, меню вложений
Клиентский объект window.WebApp из max-web-app.js window.Telegram.WebApp из telegram-web-app.js
Диплинк https://max.ru/<бот>?startapp= , payload до 512 символов t.me/<бот>?startapp= или t.me/<бот>/<app>
Проверка данных HMAC-SHA256, ключ WebAppData Тот же алгоритм
Нижние нативные кнопки Нет аналога MainButton/SecondaryButton в Bridge MainButton и SecondaryButton
Оплата из мини-приложения Методов оплаты в Bot API нет; ссылка на провайдера Провайдеры + Stars, openInvoice
Облачное хранилище DeviceStorage / SecureStorage на устройстве CloudStorage до 1024 ключей + DeviceStorage / SecureStorage
Несколько окон Новое закрывает текущее Обычное поведение вкладок/шторки клиента

Меню, корзина, слоты самовывоза, админка и база заказов могут быть общими для обеих платформ. Меняются оболочка (скрипт клиента), проверка токена конкретного бота и способ открытия.

Что переносится, если Mini App уже есть в Telegram

Фронтенд режут на три слоя:

  1. Бизнес-экран — каталог, форма, корзина. Его трогать почти не нужно.
  2. Адаптер платформы — тонкая обёртка: где взять initData, как показать «Назад», как вибрануть, как открыть внешнюю ссылку. В Telegram это вызовы Telegram.WebApp.*, в MAX — WebApp.* с другими именами.
  3. Бэкенд — один. Два токена ботов, две проверки подписи (алгоритм один, секреты разные), общие заказы и статусы.

На практике для «Зерно и Пар» меню из 16 позиций, настройка напитка и слоты самовывоза живут в одной вёрстке. Telegram-ветка подключает telegram-web-app.js и нативные кнопки; браузерная открывает ту же страницу без мессенджера. Ветку для MAX делают так же: другой скрипт, другая кнопка запуска, тот же API заказов. Как устроен сам Telegram Mini App для кафе, разобрано отдельно: «Telegram Mini App для кафе и магазина».

Перенос ботовой части (сообщения, вебхук, кнопки) — другая задача. Её я расписал в «Как перенести Telegram-бота в MAX».

Для каких задач это подходит

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

Не стоит ждать от MAX Mini App того, чего нет в API. Если нужна оплата внутри шторки одним тапом — пока только редирект на ЮKassa или другого провайдера, а бот меняет статус после вебхука оплаты. Если нужна витрина в глобальном каталоге приложений Telegram — в MAX такого магазина в документации нет.

Ориентир по срокам и деньгам зависит от объёма экранов и интеграций. Простая витрина с корзиной и уведомлением в чат обычно ближе к срокам обычного лендинга плюс бот; каталог на сотни позиций с личным кабинетом и синхронизацией остатков — уже полноценный веб-проект. Из чего складывается бюджет бота и приложений вокруг него — в статье «Сколько стоит разработать чат-бота для MAX».

С чего начать

  1. Зарегистрируйте организацию и бота на платформе партнёров заранее: модерация идёт параллельно с вёрсткой.
  2. Выложите черновик страницы на HTTPS и пропишите URL в настройках бота — так сразу проверяется кнопка запуска на телефоне.
  3. Подключите max-web-app.js, выведите platform и initDataUnsafe.user на экран отладки.
  4. Сразу напишите проверку initData на бэкенде и гоняйте её автотестом: без этого любой следующий экран бессмысленен.
  5. Если уже есть Telegram Mini App — вынесите вызовы Telegram.WebApp в адаптер, прежде чем копировать экраны.

Документация MAX за 2026 год уже несколько раз меняла адреса API и детали платформы. Перед стартом откройте dev.max.ru/docs/webapps/introduction в день работ и сверьте лимиты startapp и список методов Bridge.

Если нужно мини-приложение в MAX под каталог, запись или кабинет — напишите, что должно происходить за первый экран. Посмотрю объём и скажу, что переедет из Telegram-версии без переписывания, а что придётся сделать отдельно.

Посмотреть вживую

Мои демо-проекты по теме статьи. Они работают, их можно открыть и потрогать. Это демонстрации, а не работы для клиентов.