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`	Скачает файл по переданной ссылке
`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`	Метод сообщает, что событие или действие выполнены успешно, не удалось или выдано предупреждение. Приложение 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 }`
`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` — пользователь закрыл камеру
`WebAppDownloadFile` `в разработке`	Скопирует файлы на устройство пользователя	-	-
`WebAppCopyText` `в разработке`	Скопирует переданный текст в буфер обмена	-	-

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