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>

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

Объекты

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`	Откроет ссылку во внешнем браузере Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, перехода по ссылке не будет
`openMaxLink()`	url: `string`	`function`	Откроет диплинк вида `https://max.ru/<some-url>` из мини-приложения внутри MAX. Если передать ссылку другого вида, метод откроет её во внешнем браузере Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, перехода по ссылке не будет
`shareContent()`	text: `string`, link: `string`	`function`	Вызовет нативный экран шеринга Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, экран шеринга не откроется
`shareMaxContent()`	Шеринг текста или ссылок: `{text: string, link: string}` Шеринг сообщения с файлом или медиа: `{mid: string, chatType: string}`	`function`	Откроет экран шеринга внутри MAX Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, экран шеринга не откроется Для шеринга файла или медиа бот, на котором работает мини-приложение, предварительно отправляет это содержимое пользователю. Для этого мини-приложение передаёт дополнительно: `mid` — идентификатор сообщения от бота пользователю `chatType` — тип чата: • `DIALOG` — для личного чата между двумя пользователями • `CHAT` — для группового чата. Пользователь должен быть участником чата В метод передаются либо `text` и/или `link`, либо `mid` и `chatType`. Если при шеринге медиа или файла передать `text` или `link`, они будут проигнорированы
`downloadFile()`	url: `string`, file_name: `string`	`function`	Скачает файл по переданной ссылке. Ссылка должна быть вида `https://..` Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, файл не будет скачен
`requestScreenMaxBrightness()`	-	`function`	Установит яркость экрана на максимум. Клиент поддержит максимальную яркость 30 секунд, затем восстановит исходное значение
`restoreScreenBrightness()`	-	`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`	Метод сообщает, что событие или действие выполнены успешно, не удалось или выдано предупреждение. Приложение MAХ может воспроизводить соответствующие тактильные сигналы на основе переданного значения типа. Тип может быть одним из следующих значений: `error` — Указывает, что задача или действие не удалось `success` — Указывает, что задача или действие были успешно завершены `warning` — Указывает, что задача или действие вызвали предупреждение
`selectionChanged`	`boolean`	Метод сообщает, что пользователь изменил выбор. Приложение MAХ может воспроизвести соответствующие тактильные сигналы. Не используйте эту обратную связь, когда пользователь делает или подтверждает выбор; используйте ее только при изменении выбора.

DeviceStorage

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

Методы DeviceStorage не поддерживаются в веб-версии

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

SecureStorage

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

Методы 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`	Предложение перейти в настройки MAХ на экран приватности, чтобы дать доступ к биометрии устройства для мини-приложения. Вызывает закрытие мини-приложение.

События 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`	Откроет ссылку во внешнем браузере Вызывается методом `openLink()` в объекте `Window.WebApp`	`{url: string}`	В случае успеха: `{ status: "opened" }` В случае ошибки: `{ error: { code: "client.open_link.<reason>" } }` Возможные значения `reason`: `parse_link_error` — передана неправильная ссылка `user_gesture_required` — необходимо активное действие (клик) пользователя в мини-приложении
`WebAppOpenMaxLink`	Открытие диплинка вида `https://max.ru/<some-url>` из мини-приложения внутри MAX Если передать ссылку другого вида, метод откроет её во внешнем браузере Вызывается методом `openMaxLink()` в объекте `Window.WebApp`	`{ url: string}`	В случае успеха: `{ status: "opened" }` В случае ошибки: `{ error: { code: "client.open_max_link.<reason>" } }` Возможные значения `reason`: `parse_link_error` — передана неправильная ссылка `user_gesture_required` — необходимо активное действие (клик) пользователя в мини-приложении
`WebAppShare`	Откроет нативный шеринг из мини-приложения Вызывается методом `shareContent()` в объекте `Window.WebApp`	`{ 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` — не передан хотя бы один параметр `user_gesture_required` — необходимо активное действие (клик) пользователя в мини-приложении
`WebAppMaxShare`	Откроет нативный шеринг из мини-приложения в личные или групповые чаты MAХ Вызывается методом `shareMaxContent()` в объекте `Window.WebApp`	`{ requestId: string, text: string, link: string, mid: string, chatType: string }` При шеринге сообщения с текстом и/или ссылкой в `eventData`будут переданы `text` и/или `link` При шеринге сообщения с файлом или медиа бот, на котором работает мини-приложение, предварительно отправит этот контент пользователю: `mid` — идентификатор сообщения от бота пользователю `chatType` — тип чата: • `DIALOG` — для личного чата между двумя пользователями • `CHAT` — для группового чата. Пользователь должен быть участником чата В метод передаются либо `text` и/или `link`, либо `mid` и `chatType`. Если при шеринге медиа или файла передать `text` или `link`, они будут проигнорированы	В случае успеха: `{ 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` — параметры переданы некорректно или один из параметров `mid` / `chatType` отсутствует в кэше `user_gesture_required` — необходимо активное действие (клик) пользователя в мини-приложении
`WebAppDownloadFile`	Скачает файлы на устройство пользователя Вызывается методом `downloadFile()` в объекте `Window.WebApp`	`{ requestId: string, url: string, file_name : string }`	В случае успеха: `{ requestId: string, status: "downloading" }` Если скачивание отменено пользователем: `{ requestId: string, status: "cancelled" }` В случае ошибки: `{ error: { code: "client.download_file.<reason>" } }` Возможные значения `reason`: `download_failed` — скачивание завершилось ошибкой `invalid_request` — отсутствует один из параметров или протокол ссылки на файл отличен от `https` `user_gesture_required` — необходимо активное действие (клик) пользователя в мини-приложении
`WebAppSetupScreenCaptureBehavior`	Управление возможностью делать скриншоты / записывать экран	В случае успеха: `{ requestId: string, isScreenCaptureEnabled: boolean }` Возможные значения `isScreenCaptureEnabled`: `true` — разрешить делать скриншоты / запись экрана `false` — запретить делать скриншоты / запись экрана	В случае успеха: `{ requestId: string, isScreenCaptureEnabled: boolean }`
`WebAppChangeScreenBrightness`	Управление яркостью экрана	`{ requestId: string, maxBrightness: boolean }` `maxBrightness: true` — установит максимальную яркость. Клиент поддержит максимальную яркость 30 секунд, затем восстановит исходное значение `maxBrightness: false` — восстановит яркость экрана до исходного значения	—
`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` — пользователь закрыл камеру

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