MAX Bridge
Библиотека MAX Bridge позволяет мини-приложениям корректно взаимодействовать с API MAX и API операционной системы на устройстве пользователя. В этом разделе содержится список объектов и событий MAX Bridge
Подключение библиотеки
Добавьте библиотеку max-web-app.js
<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 в разработке | Копирует переданный текст в буфер обмена | - | - |
Если у вас возникли вопросы, посмотрите раздел с ответами