MAX Bridge

Библиотека MAX Bridge позволяет мини-приложениям корректно взаимодействовать с API MAX и API операционной системы на устройстве пользователя. В этом разделе содержится список объектов и событий MAX Bridge

Подключение библиотеки

Добавьте библиотеку max-web-app.js

HTML
Скопировать
<script src="https://st.max.ru/js/max-web-app.js"></script>

С подключением библиотеки мини-приложение получит доступ к глобальному объекту WebApp в window и сценариям для его использования

Объекты

Window.WebApp

Этот глобальный объект связывает мини-приложение с клиентом и позволяет взаимодействовать с MAX, управлять интерфейсом приложения и получать информацию о пользователях. Объект window.WebApp создаётся с каждым запуском сервиса, предзагружает данные и не требует отдельной инициализации — его методы и параметры доступны напрямую

ПолеТип данныхОписание
initDatastringОбъект со стартовыми параметрами, который как и WebAppData, применяется для отображения данных о пользователе в UI
initDataUnsafeWebAppDataОбъект со стартовыми параметрами, который не должен использоваться для валидации пользователей
onEvent()functionПодпишет на событие с использованием callback
ready()functionСообщит MAX, что мини-приложение готово к работе
close()functionЗакроет мини-приложение
requestContact()functionПопросит телефон у пользователя в нативном диалоговом окне
BackButtonBackButtonУправляет кнопкой Назад в шапке мини-приложения
enableClosingConfirmation()functionПредупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение
disableClosingConfIrmation()functionНе предупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение
openLink()functionОткроет ссылку во внешнем браузере
openMaxLink()functionОткроет другое мини-приложение внутри MAX, закрыв текущее. Ссылка должна быть вида

https://max.ru/<botName>?startapp
downloadFile()string, stringВходные параметры: url, file_name

Метод, который используется для вызова нативного экрана шаринга.

WebAppData

Этот объект содержит данные, которые мини-приложение получает при запуске. Совпадает с initData

ПараметрТип данныхОписание
query_idstringУникальный идентификатор сессии мини-приложения
auth_dateint32Время получения данных с бэкенда
hashstringХэш переданных параметров, который можно использовать для проверки их достоверности
start_paramWebAppStartParamОбъект с дополнительными данными
userobjectОбъект с данными о пользователе, который открывает мини-приложение
idint64Уникальный идентификатор пользователя MAX
first_namestringИмя пользователя
last_namestringФамилия пользователя
usernamestringНик пользователя
language_code
stringЯзык интерфейса MAX
photo_urlstringСсылка на фото профиля пользователя
chatChatОбъект с данными о чате, из которого открыто мини-приложение
idnumberИдентификатор чата
typestringТип чата

WebAppStartParam

Этот объект содержит дополнительные данные, которые мини-приложение получает при запуске. Данные передаются в URL мини-приложения в поле startapp?=PARAMS

Передать можно максимум 512 символов. Если символов больше, объект будет удалён из URL-ответа. Разрешены символы A-Z, a-z, 0-9, _ (подчеркивание) и - (минус)

BackButton

Этот объект управляет кнопкой Назад в шапке мини-приложения

ПолеТип данныхОписание
isVisiblebooleanЗадаёт состояние false по умолчанию
onClick()functionУстанавливает обработчик событий
offClick()functionУбирает обработчик событий нажатия кнопки
show()functionДелает кнопку Назад активной и видимой
hide()functionСкрывает кнопку Назад

DeviceStorage

Этот объект предоставляет мини-приложению доступ к хранилищу данных, ассоциированному с конкретным пользователем MАХ

Название метода в объекте window.WebApp.DeviceStorage
Входные параметрыТип данныхОписание
setItem()key, valuestring, stringСохраняет переданную пару «ключ-значение» в локальном хранилище устройства
getItem()keystringПолучает значение из локального хранилища устройства по указанному ключу
removeItem()keystringУдаляет значение из локального хранилища устройства по указанному ключу
clear()--Очищает все ключи, ранее сохранённые ботом в локальном хранилище устройства

SecureStorage

Этот объект предоставляет мини-приложению доступ к защищённому хранилищу данных

Название метода в объекте window.WebApp.SecureStorage
Входные параметрыТип данныхОписание
setItem()key, valuestring, stringСохраняет переданную пару «ключ-значение» в защищённом хранилище устройства
getItem()keystringПолучает значение из защищённого хранилища устройства по указанному ключу
removeItem()keystringУдаляет значение из защищённого хранилища устройства по указанному ключу

BiometricManager

Этот объект нужен для аутентификации, когда доступ к данным в keychain получается через биометрические идентификаторы Перед первым использованием этого объекта его необходимо инициализировать с помощью метода init.

ПолеТип данныхОписание
isInitedbooleanБыла ли ранее проведена первичная инициализация
initfunctionПервичная инициализация биометрии
  • Проверяем доступность биометрии на устройстве
  • Проверяем предоставлен ли доступ

Вызывается единожды при самом первом использовании.
isBiometricAvailablebooleanДоступна ли биометрия на устройстве пользователя, который запустил мини приложение

false, если пользователь отказался предоставить доступ к биометрии
biometricTypestring[]
  • fingerprint
  • faceid
  • unknown

Если пользователь отказался предоставить доступ к биометрии, biometricType=["unknown"]
Для android всегда ["unknown"]
deviceIdstring | nullИдентификатор устройства (можно использовать для сопоставления токена с устройством)

null, если пользователь отказался предоставить доступ к биометрии
isAccessRequestedbooleanБыл ли ранее отправлен запрос на предоставление доступа к биометрии устройства

false, если пользователь отказался предоставить доступ к биометрии
isAccessGrantedbooleanПредоставлен ли доступ к биометрии

false, если пользователь отказался предоставить доступ к биометрии
isBiometricTokenSavedbooleanЕсть ли токен в безопасном хранилище устройства

false, если пользователь отказался предоставить доступ к биометрии
requestAccessfunctionЗапросить доступ на использование биометрии на устройстве
authenticatefunctionДля запуска процесса аутентификации
updateBiometricTokenfunctionМетод, который обновляет биометрический токен в безопасном хранилище на устройстве

Чтобы удалить токен, передайте пустую строку.
openSettingsfunctionПредложение перейти в настройки Max на экран приватности, чтобы дать доступ к биометрии устройства для мини приложения.

Вызывает закрытие мини приложение.

События Bridge

НазваниеОписаниеeventDataЧто отвечает
WebAppReadyСигнализирует нативному приложению, что миниапп готов к работе.

Если контент мини приложения не был загружен за 15 секунд - клиент отобразит экран с ошибкой "нет сети".

Если контент мини приложения был загружен ИЛИ было вызвано событие WebAppReady на платформе - платформа отображает загруженную страницу.

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

Мини приложению не требуется промис со стороны нативного клиента.
--
WebAppSetupBackButtonУправляет поведением кнопки назад, которая может отображаться в заголовке мини приложения в интерфейсе MAX

isVisible = true - кнопка назад отображается

isVisible = false - кнопка назад не отображается
isVisible: boolean-
WebAppRequestPhoneПолучив это событие, клиенты должны показать пользователю сообщение, указывающее, что мини приложение просит его поделиться своим номером телефона.

Мини приложению требуется промис со стороны нативного клиента.
-phone: string
WebAppSetupClosingBehaviorУправляет поведением окна с запущенным мини приложением

needConfirmation = true - клиент должен запрашивать подтверждение пользователя с помощью всплывающего окна «Внесенные вами изменения могут быть не сохранены»

needConfirmation = false - клиент не будет запрашивать

Если явно не передано - запрашиваться не будет.
needConfirmation: boolean-
WebAppBackButtonPressedУведомление о том, что кнопка "Назад" была нажата пользователем--
WebAppOpenLinkОткрытие ссылки во внешнем браузереurl: string-
WebAppOpenMaxLinkОткрытие диплинка MAX внутри клиентаpath: string-
WebAppShare
в разработке
Нативный шаринг из миниприложения--
WebAppDownloadFile
в разработке
Позволяет скачивать файлы на устройство пользователя--
WebAppCopyText
в разработке
Копирует переданный текст в буфер обмена--

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