Подключение мини-приложения

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

Мини-приложения работают только внутри MAX и не могут существовать автономно. Они расширяют функциональность основной платформы и позволяют разработчикам быстро запускать проекты

Что потребуется

• Устройства с операционной системой Windows, macOS или Linux
• Мобильное устройство для регистрации профиля в MAX
• Редактор кода и навыки работы с командной строкой

Что упростит разработку

• Библиотека MAX Bridge, с которой мини-приложение сможет взаимодействовать с API MAX и API устройства пользователя
• Библиотека React-компонентов MAX UI, с которой мини-приложение легко стилизовать под интерфейс MAX
• Мини-приложения работают на базе стандартных веб-технологий — HTML, JavaScript, CSS

Перед подключением

• Загрузите файлы мини-приложения на хостинг статики, например, через Vercel или GitHub Pages — .html, .css, .js и другие медиафайлы
• Проверьте, что приложение работает по защищённому соединению — https

Как добавить приложение в MAX

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

Требования к URL мини-приложения:

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

Как только вы подключите мини-приложение к платформе, в чате с его ботом появится заметная кнопка для быстрого запуска сервиса

Запуск мини-приложения из чата с ботом

Как работать с диплинками

Диплинки (deep links) — это специальные ссылки, которые позволяют открывать приложения MAX с передачей дополнительных параметров. С их помощью можно передавать контекстную информацию, отслеживать источники переходов или автоматически выполнять определённые действия при запуске

Создание диплинка приложения

Чтобы создать диплинк мини-приложения, используйте следующий формат ссылки:

Где:

• <botName> — имя бота, к которому привязано мини-приложение
• <payload> — необязательный параметр с дополнительными данными (до 512 символов)

Примеры
Базовая ссылка без параметров

Ссылка с параметрами

Ссылка с составными параметрами

Payload в приложении

При работе с payload для мини-приложений обратите внимание на допустимые символы:

• Латинские буквы: A-Z, a-z
• Цифры: 0-9
• Специальные символы: _ (подчёркивание), - (дефис)

Если payload превышает 512 символов или содержит недопустимые символы, он будет удалён из URL-ответа

Как получить payload в мини-приложении

После подключения библиотеки MAX Bridge мини-приложение получает доступ к глобальному объекту window.WebApp, который содержит стартовые параметры

Переданные параметры доступны через:

• initDataUnsafe.start_param — объект WebAppStartParam с данными из URL
• initData — строка, которая содержит все стартовые параметры в текстовом формате

Как управлять приложением

Обновление ссылки на приложение

Если ссылка поменялась, самостоятельно обновите её на платформе MAX для партнёров: зайдите в профиль организации → перейдите в раздел Чат-бот и мини-приложение → Настроить → в поле с URL обновите ссылку → нажмите Сохранить

Изменение кнопки открытия приложения

Чтобы изменить кнопку открытия, в платформе MAX для партнёров зайдите в профиль организации → перейдите в раздел Чат-бот и мини-приложение → Настроить → выберите нужный вид кнопки → нажмите Сохранить

Удаление приложения

Если вы хотите удалить мини-приложение, в платформе MAX для партнёров зайдите в профиль организации → перейдите в раздел Чат-бот и мини-приложение → Настроить → в поле с URL удалите ссылку на мини-приложение → нажмите Сохранить

Как открыть приложение по прямой ссылке

Каждое мини-приложение можно открыть внутри MAX по ссылке вида: https://max.ru/<botName>?startapp

После ключа ?startapp в ссылку можно добавить стартовые параметры. Они будут переданы мини-приложению в поле start_param и в GET-параметре WebAppStartParam

Подробнее о стартовых параметрах читайте в разделе WebAppStartParam

Если у вас возникли вопросы, посмотрите раздел с ответами