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 создаётся с каждым запуском сервиса, предзагружает данные и не требует отдельной инициализации — его методы и параметры доступны напрямую
| Поле | Тип данных | Описание |
|---|---|---|
initData | string | Объект со стартовыми параметрами, который как и WebAppData, применяется для отображения данных о пользователе в UI |
initDataUnsafe | WebAppData | Объект со стартовыми параметрами, который не должен использоваться для валидации пользователей |
onEvent() | function | Подпишет на событие с использованием callback |
ready() | function | Сообщит MAX, что мини-приложение готово к работе |
close() | function | Закроет мини-приложение |
requestContact() | function | Попросит телефон у пользователя в нативном диалоговом окне |
BackButton | BackButton | Управляет кнопкой Назад в шапке мини-приложения |
enableClosingConfirmation() | function | Предупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение |
disableClosingConfIrmation() | function | Не предупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение |
openLink() | function | Откроет ссылку во внешнем браузере |
openMaxLink() | function | Откроет другое мини-приложение внутри MAX, закрыв текущее. Ссылка должна быть видаhttps://max.ru/<botName>?startapp |
downloadFile() | string, string | Входные параметры: url, file_nameМетод, который используется для вызова нативного экрана шаринга. |
WebAppData
Этот объект содержит данные, которые мини-приложение получает при запуске. Совпадает с initData
| Параметр | Тип данных | Описание |
|---|---|---|
query_id | string | Уникальный идентификатор сессии мини-приложения |
auth_date | int32 | Время получения данных с бэкенда |
hash | string | Хэш переданных параметров, который можно использовать для проверки их достоверности |
start_param | WebAppStartParam | Объект с дополнительными данными |
user | object | Объект с данными о пользователе, который открывает мини-приложение |
• id | int64 | Уникальный идентификатор пользователя MAX |
• first_name | string | Имя пользователя |
• last_name | string | Фамилия пользователя |
• username | string | Ник пользователя |
• language_code | string | Язык интерфейса MAX |
• photo_url | string | Ссылка на фото профиля пользователя |
chat | Chat | Объект с данными о чате, из которого открыто мини-приложение |
• id | number | Идентификатор чата |
• type | string | Тип чата |
WebAppStartParam
Этот объект содержит дополнительные данные, которые мини-приложение получает при запуске. Данные передаются в URL мини-приложения в поле startapp?=PARAMS
Передать можно максимум 512 символов. Если символов больше, объект будет удалён из URL-ответа. Разрешены символы A-Z, a-z, 0-9, _ (подчеркивание) и - (минус)
BackButton
Этот объект управляет кнопкой Назад в шапке мини-приложения
| Поле | Тип данных | Описание |
|---|---|---|
isVisible | boolean | Задаёт состояние false по умолчанию |
onClick() | function | Устанавливает обработчик событий |
offClick() | function | Убирает обработчик событий нажатия кнопки |
show() | function | Делает кнопку Назад активной и видимой |
hide() | function | Скрывает кнопку Назад |
DeviceStorage
Этот объект предоставляет мини-приложению доступ к хранилищу данных, ассоциированному с конкретным пользователем MАХ
Название метода в объекте window.WebApp.DeviceStorage | Входные параметры | Тип данных | Описание |
|---|---|---|---|
setItem() | key, value | string, string | Сохраняет переданную пару «ключ-значение» в локальном хранилище устройства |
getItem() | key | string | Получает значение из локального хранилища устройства по указанному ключу |
removeItem() | key | string | Удаляет значение из локального хранилища устройства по указанному ключу |
clear() | - | - | Очищает все ключи, ранее сохранённые ботом в локальном хранилище устройства |
SecureStorage
Этот объект предоставляет мини-приложению доступ к защищённому хранилищу данных
Название метода в объекте window.WebApp.SecureStorage | Входные параметры | Тип данных | Описание |
|---|---|---|---|
setItem() | key, value | string, string | Сохраняет переданную пару «ключ-значение» в защищённом хранилище устройства |
getItem() | key | string | Получает значение из защищённого хранилища устройства по указанному ключу |
removeItem() | key | string | Удаляет значение из защищённого хранилища устройства по указанному ключу |
BiometricManager
Этот объект нужен для аутентификации, когда доступ к данным в keychain получается через биометрические идентификаторы
Перед первым использованием этого объекта его необходимо инициализировать с помощью метода init.
| Поле | Тип данных | Описание |
|---|---|---|
isInited | boolean | Была ли ранее проведена первичная инициализация |
init | function | Первичная инициализация биометрии
Вызывается единожды при самом первом использовании. |
isBiometricAvailable | boolean | Доступна ли биометрия на устройстве пользователя, который запустил мини приложениеfalse, если пользователь отказался предоставить доступ к биометрии |
biometricType | string[] |
Если пользователь отказался предоставить доступ к биометрии, biometricType=["unknown"]Для android всегда ["unknown"] |
deviceId | string | null | Идентификатор устройства (можно использовать для сопоставления токена с устройством)null, если пользователь отказался предоставить доступ к биометрии |
isAccessRequested | boolean | Был ли ранее отправлен запрос на предоставление доступа к биометрии устройстваfalse, если пользователь отказался предоставить доступ к биометрии |
isAccessGranted | boolean | Предоставлен ли доступ к биометрииfalse, если пользователь отказался предоставить доступ к биометрии |
isBiometricTokenSaved | boolean | Есть ли токен в безопасном хранилище устройстваfalse, если пользователь отказался предоставить доступ к биометрии |
requestAccess | function | Запросить доступ на использование биометрии на устройстве |
authenticate | function | Для запуска процесса аутентификации |
updateBiometricToken | function | Метод, который обновляет биометрический токен в безопасном хранилище на устройстве Чтобы удалить токен, передайте пустую строку. |
openSettings | function | Предложение перейти в настройки Max на экран приватности, чтобы дать доступ к биометрии устройства для мини приложения. Вызывает закрытие мини приложение. |
События Bridge
| Название | Описание | eventData | Что отвечает |
|---|---|---|---|
WebAppReady | Сигнализирует нативному приложению, что миниапп готов к работе. Если контент мини приложения не был загружен за 15 секунд - клиент отобразит экран с ошибкой "нет сети". Если контент мини приложения был загружен ИЛИ было вызвано событие WebAppReady на платформе - платформа отображает загруженную страницу.Мини приложению не требуется промис со стороны нативного клиента. | - | - |
WebAppClose | Сигнализирует нативному приложению, что миниап должен быть закрыт. Мини приложению не требуется промис со стороны нативного клиента. | - | - |
WebAppSetupBackButton | Управляет поведением кнопки назад, которая может отображаться в заголовке мини приложения в интерфейсе MAXisVisible = 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в разработке | Копирует переданный текст в буфер обмена | - | - |
Если у вас возникли вопросы, посмотрите раздел с ответами