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 создаётся с каждым запуском сервиса, предзагружает данные и не требует отдельной инициализации — его методы и параметры доступны напрямую

Версия приложения MAX передаётся в стартовых параметрах URL через WebAppVersion и доступна в свойстве version объекта window.WebApp. Этот параметр не участвует в формировании хеша для валидации — в хеше учитываются только данные из WebAppData

Поле	Входные параметры	Тип данных	Описание
`initData`	-	`string`	Объект со стартовыми параметрами, который как и WebAppData, применяется для отображения данных о пользователе в UI
`initDataUnsafe`	-	`WebAppData`	Объект со стартовыми параметрами, который не должен использоваться для валидации пользователей
`platform`	-	`string`	Платформа, с которой запущено мини-приложение. Возможные значения: `ios`, `android`, `desktop`, `web`
`version`	-	`string`	Версия приложения MAX, с которого запущено мини-приложение. Имеет формат `<year>.<build_number — возрастающий счётчик>.<patch_version — для патчей>`, например `25.9.16`
`onEvent()`	eventName: `string`, callback: `function`	`function`	Подпишет на событие с использованием callback
`offEvent()`	eventName: `string`, callback: `function`	`function`	Отпишет callback от события
`ready()`	-	`function`	Сообщит MAX, что мини-приложение готово к работе
`close()`	-	`function`	Закроет мини-приложение
`requestContact()`	-	`function`	Попросит телефон у пользователя в нативном диалоговом окне
`BackButton`	-	`BackButton`	Управляет кнопкой Назад в шапке мини-приложения
`ScreenCapture`	-	`ScreenCapture`	Объект для управления возможностью делать скриншоты / записывать экран
`HapticFeedback`	-	`HapticFeedback`	Объект для управления тактильными вибро-откликами
`enableClosingConfirmation()`	-	`function`	Предупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение
`disableClosingConfirmation()`	-	`function`	Не предупредит пользователя о риске потерять заполненные данные, если закрыть мини-приложение
`openLink()`	url: `string`	`function`	Откроет ссылку во внешнем браузере
`openMaxLink()`	url: `string`	`function`	Откроет другое мини-приложение внутри MAX, закрыв текущее. Ссылка должна быть вида `https://max.ru/<botName>?startapp`
`shareContent()`	text: `string`, link: `string`	`function`	Метод, который используется вызова нативного экрана шаринга
`shareMaxContent()`	text: `string`, link: `string`	`function`	Метод, который используется для вызова экрана шаринга внутри Max
`downloadFile()`	url: `string`, fileName: `string`	`function`	Метод, который используется для скачивания файла по переданной ссылке
`openCodeReader()`	fileSelect: `boolean`	`function`	Открыть камеру для считывания QR кода. Клиент вернет результат в виде строки (если QR код был найден и распознан) `fileSelect = true` - доступен так же выбор из галереи `fileSelect = false` - доступно сканирование только через камеру Если fileSelect не передан - по умолчанию считается `true`

WebAppData

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

Параметр	Тип данных	Описание
`query_id`	`string`	Уникальный идентификатор сессии мини-приложения
`auth_date`	`int32`	Время получения данных с бэкенда
`hash`	`string`	Хэш переданных параметров, который можно использовать для проверки их достоверности
`start_param`	`WebAppStartParam`	Объект с дополнительными данными
`user`	`object`	Объект с данными о пользователе, который открывает мини-приложение
`user.id`	`int64`	Уникальный идентификатор пользователя MAX
`user.first_name`	`string`	Имя пользователя
`user.last_name`	`string`	Фамилия пользователя
`user.username`	`string`	Ник пользователя
`user.language_code`	`string`	Язык интерфейса MAX
`user.photo_url`	`string`	Ссылка на фото профиля пользователя
`chat`	`Chat`	Объект с данными о чате, из которого открыто мини-приложение
`chat.id`	`number`	Идентификатор чата
`chat.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`	Скрывает кнопку Назад

ScreenCapture

Этот объект управляет возможностью делать скриншоты / записывать экран

Поле	Тип данных	Описание
`isScreenCaptureEnabled`	`boolean`	Геттер, который позволяет узнать, разрешено ли делать скриншоты / запись экрана в данный момент `true` - запрещено `false` - разрешено `false` по умолчанию
`enableScreenCapture()`	`function`	Включить запрет на скриншоты / запись экрана
`disableScreenCapture()`	`function`	Отключить запрет на скриншоты / запись экрана

HapticFeedback

Этот объект используется для активации тактильной обратной связи при взаимодействии пользователя с веб-приложением.

Поле	Тип данных	Описание
`impactOccurred(impactStyle, disableVibrationFallback)`	`string`, `boolean`	Метод сообщает, что произошло воздействие. Приложение Max может воспроизвести соответствующие тактильные эффекты на основе переданного значения стиля. Стиль может иметь одно из следующих значений: `soft` - мягкая вибрация `light` - лёгкая вибрация `medium` - средняя вибрация `heavy` - сильная вибрация `rigid` - жёсткая вибрация
`notificationOccurred(notificationType, disableVibrationFallback)`	`string`, `boolean`	Метод сообщает, что событие или действие выполнены успешно, не удалось или выдано предупреждение. Приложение Max может воспроизводить соответствующие тактильные сигналы на основе переданного значения типа. Тип может быть одним из следующих значений: `error` - Указывает, что задача или действие не удалось `success` - Указывает, что задача или действие были успешно завершены `warning` - Указывает, что задача или действие вызвали предупреждение
`selectionChanged`	`boolean`	Метод сообщает, что пользователь изменил выбор. Приложение Max может воспроизвести соответствующие тактильные сигналы. Не используйте эту обратную связь, когда пользователь делает или подтверждает выбор; используйте ее только при изменении выбора.

DeviceStorage

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

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

SecureStorage

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

Поле	Входные параметры	Тип данных	Описание
`setItem()`	`key`, `value`	`string`, `string`	Сохраняет переданную пару «ключ-значение» в защищённом хранилище устройства
`getItem()`	`key`	`string`	Получает значение из защищённого хранилища устройства по указанному ключу
`removeItem()`	`key`	`string`	Удаляет значение из защищённого хранилища устройства по указанному ключу

BiometricManager

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

Поле	Тип данных	Описание
`isInited`	`boolean`	Была ли ранее проведена первичная инициализация
`init`	`function`	Первичная инициализация биометрии Проверяем доступность биометрии на устройстве Проверяем предоставлен ли доступ Вызывается единожды при самом первом использовании.
`isBiometricAvailable`	boolean	Доступна ли биометрия на устройстве пользователя, который запустил мини-приложение `false`, если пользователь отказался предоставить доступ к биометрии
`biometricType`	`string[]`	`fingerprint` `faceid` `unknown` Если пользователь отказался предоставить доступ к биометрии, `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`	Управляет поведением кнопки назад, которая может отображаться в заголовке мини-приложения в интерфейсе 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`	Нативный шаринг из мини-приложения	`{ requestId: string, text: string, link: string }` Максимальная длина - 200 символов	В случае успеха: `{ requestId: string, status: "shared" }` В случае если шторка была закрыта: `{ requestId: string, status: "cancelled" }` В случае ошибки: `{ error: { code: "client.web_app_share.<reason>" } }` Возможные значения reason: `too_large_text` - слишком длинный текст `too_large_link` - слишком длинная ссылка `invalid_request` - не передан хотя бы один параметр
`WebAppMaxShare`	Шаринг из мини-приложения в диалоги / групповые чаты Max	`{ requestId: string, text: string, link: string }`	В случае успеха: `{ requestId: string, status: "shared" }` В случае если шторка была закрыта: `{ requestId: string, status: "cancelled" }` В случае ошибки: `{ error: { code: "client.web_app_max_share.<reason>" } }` Возможные значения reason: `too_large_text` - слишком длинный текст `too_large_link` - слишком длинная ссылка `invalid_request` - не передан хотя бы один параметр
`WebAppSetupScreenCaptureBehavior`	Управление возможностью делать скриншоты / записывать экран	В случае успеха: `{ requestId: string, isScreenCaptureEnabled: boolean }` Возможные значения isScreenCaptureEnabled: `true` - разрешить делать скриншоты / запись экрана `false` - запретить делать скриншоты / запись экрана	В случае успеха: `{ requestId: string, isScreenCaptureEnabled: boolean }`
`WebAppHapticFeedbackImpact`	В случае когда произошел тактильный отклик (необходимо вызвать вибрацию)	В случае успеха: `{ requestId: string, impactStyle: string, disableVibrationFallback: boolean }` Возможные значения impactStyle: `soft` - мягкая вибрация `light` - лёгкая вибрация `medium` - средняя вибрация `heavy` - сильная вибрация `rigid` - жёсткая вибрация `disableVibrationFallback` - разрешение использовать вибрацию с постоянной амплитудой на устройствах, которые не поддерживают вибрацию с переменной амплитудой. Значение по умолчанию: `false`.	В случае успеха: `{ requestId: string, status: "impactOccured" }` В случае ошибки: `{ error: { code: "client.haptic_feedback_impact.<reason>" } }` Возможные значения reason: `not_supported` - haptic feedback недоступен на устройстве `invalid_impact_style` - передан неизвестный impact style
`WebAppHapticFeedbackNotification`	В случае когда событие или действие выполнены успешно, не выполнены или выдано предупреждение	В случае успеха: `{ requestId: string, fileSelect: boolean }` Возможные значения notificationType: `error` - Указывает, что задача или действие не удалось `success` - Указывает, что задача или действие были успешно завершены `warning` - Указывает, что задача или действие вызвали предупреждение `disableVibrationFallback` - разрешение использовать вибрацию с постоянной амплитудой на устройствах, которые не поддерживают вибрацию с переменной амплитудой. Значение по умолчанию: `false`.	В случае успеха: `{ requestId: string, status: "notificationOccured" }` В случае ошибки: `{ error: { code: "client.haptic_feedback_notification.<reason>" } }` Возможные значения reason: `not_supported` - haptic feedback недоступен на устройстве `invalid_notification_type` - передан неизвестный notification type
`WebAppHapticFeedbackSelectionChange`	Сообщает генератору виброотклика, что пользователь изменил выбор.	В случае успеха: `{ requestId: string, disableVibrationFallback: boolean }` `disableVibrationFallback` - разрешение использовать вибрацию с постоянной амплитудой на устройствах, которые не поддерживают вибрацию с переменной амплитудой. Значение по умолчанию: `false`.	В случае успеха: `{ requestId: string, status: "selectionChanged" }` В случае ошибки: `{ error: { code: "client.haptic_feedback_selection_change.<reason>" } }` Возможные значения reason: `not_supported` - haptic feedback недоступен на устройстве
`WebAppOpenCodeReader`	Открывает камеру для считывания QR кода и получает результат сканирования. Клиент не имеет возможности ответить, что код не был найден.	В случае успеха: `{ requestId: string, fileSelect: boolean }` `fileSelect = true` - доступен так же выбор из галереи `fileSelect = false` - доступно сканирование только через камеру	В случае успеха: `{ requestId: string, value: string }` В случае ошибки: `{ error: { code: "client.open_code_reader.<reason>" } }` Возможные значения reason: `not_supported` - на устройстве нет камеры `permission_denied` - пользователь не дал доступ к камере `cancelled` - пользователь закрыл камеру
`WebAppDownloadFile` `в разработке`	Позволяет скачивать файлы на устройство пользователя	-	-
`WebAppCopyText` `в разработке`	Копирует переданный текст в буфер обмена	-	-

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