MAX Bridge

Библиотека MAX Bridge позволяет мини-приложениям корректно взаимодействовать с API MAX и API операционной системы на устройстве пользователя

Подключение библиотеки

Через CDN добавьте библиотеку max-web-app.js

HTML

Скопировать

<script src="https://st.max.ru/js/max-web-app.js"></script>

После подключения библиотеки мини-приложение получит доступ к объекту WebApp через глобальный объект window

JAVASCRIPT

Скопировать

window.WebApp

window.WebApp — это глобальный объект, который связывает мини-приложение с клиентом и позволяет взаимодействовать с МAX, управлять интерфейсом приложения и получать информацию о пользователях. Объект создаётся с каждым запуском сервиса, предзагружает данные и не требует отдельной инициализации: его методы и параметры доступны напрямую

Функциональность библиотеки

Работа с данными инициализации

Чтобы получить инициализационные данные, в объекте WebApp предусмотрены следующие методы:

initData
initDataUnsafe
platform
version
deviceName

window.WebApp.initData

Строка со стартовыми параметрами в URL-кодировке. Содержит данные о пользователе и другие инициализационные данные в виде закодированной в UTF-8 строки для валидации на стороне сервера

Тип возвращаемых данных

JAVASCRIPT

Скопировать

string

window.WebApp.initDataUnsafe

Объект, который содержит данные из initData в виде JSON-объекта

Обратите внимание, что объект нельзя использовать для валидации данных

Пример

Пример объекта

Как использовать метод

JAVASCRIPT

Скопировать


interface InitData {
    query_id: string;
    ip?: string;
    auth_date: number;
    hash: string;
    user: {
        id: number;
        first_name: string;
        last_name: string;
        username: string;
        language_code: string;
        photo_url: string;
    };
    chat: {
        id: number;
        type: 'DIALOG' | 'CHAT' | 'CHANNEL';
    };
    start_param: string;
}

Описание свойств объекта

Поле	Тип данных	Описание
`query_id`	`string`	Уникальный идентификатор текущей сессии
`ip?`	`string`	IP-адрес пользователя
`auth_date`	`number`	Время выдачи данных. Позволяет определить момент инвалидации данных. Рекомендуемый интервал составляет 1 час
`hash`	`string`	Хеш переданных параметров, который можно использовать для проверки их достоверности
`user`	`object`	Объект содержит данные о пользователе, который открывает мини-приложение
`user.id`	`number`	Идентификатор пользователя
`user.first_name`	`string`	Имя пользователя
`user.last_name`	`string`	Фамилия пользователя
`user.username`	`string`	Никнейм пользователя
`user.language_code`	`string`	Язык интерфейса приложения MAX
`user.photo_url`	`string`	Ссылка на фото профиля пользователя
`chat`	`object`	Объект содержит данные о чате, в котором открыто мини-приложение
`chat.id`	`number`	Идентификатор чата
`chat.type`	`string`	Тип чата (`DIALOG` / `CHAT` / `CHANNEL`)
`start_param`	`string`	Значение, переданное в мини-приложение через query-параметр Пример: `https://max.ru/<your_awesome_bot>?startapp=someData`, где поле `start_param` будет содержать значение `someData`

window.WebApp.platform

Платформа, с которой запущено мини-приложение. Возможные значения:

ios
android
desktop
web

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

string

window.WebApp.version

Версия приложения MAX, с которого запущено мини-приложение

Имеет формат <year>.<build_number — возрастающий счётчик>.<patch_version — для патчей>, например 25.9.16

Этот параметр не участвует в формировании хеша для валидации — в хеше учитываются только данные из WebAppData

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

string

window.WebApp.deviceName

Возвращает устройство, с которого запущено мини-приложение. Например, может возвращать:

network name, macOS Tahoe (26.6) — десктоп-приложение на macOS
network name, Windows 11 Version 25H2 — десктоп-приложение на Windows
Google Pixel 6, Android 17 — мобильное приложение Android
iPhone 16, iOS 26.5 — мобильное приложение iOS
Chrome, macOS — веб-приложение на macOS
Chrome, Windows — веб-приложение на Windows

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

string

Контекст запущенного приложения

window.WebApp.getLaunchContext()

Позволяет мини-приложению адаптировать поведение и интерфейс в зависимости от источника запуска — это может быть таббар (нижняя панель вкладок приложения MAX) или список чатов, экран чата, экран настроек

Метод доступен для версий:

Android — 26.19.2 и выше

iOS — 26.20.0 и выше

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{
  entryPoint: 'tabbar' | 'default'
}>

entryPoint = tabbar — мини приложение запущено из таббара
entryPoint = default — мини приложение запущено из списка чатов / экрана чата / экрана настроек

Работа с экраном

window.WebApp.requestScreenMaxBrightness()

Устанавливает яркость экрана пользователя на максимум

Приложение поддержит максимальную яркость 30 секунд, затем восстановит исходное значение

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{maxBrightness: boolean}>

window.WebApp.restoreScreenBrightness()

Восстанавливает яркость экрана пользователя до исходного значения

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{maxBrightness: boolean}>

window.WebApp.ScreenCapture.enableScreenCapture()

Включает возможность делать скриншоты или записывать экран

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{isScreenCaptureEnabled: boolean}>

window.WebApp.ScreenCapture.disableScreenCapture()

Отключает возможность делать скриншоты или записывать экран

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{isScreenCaptureEnabled: boolean}>

window.WebApp.getViewportSize()

Возвращает текущий размер доступной области просмотра мини-приложения (viewport). Эти данные необходимо учитывать для корректного отображения мини-приложения

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{
    height: string,          
    width: string           
    }>

Запрос номера телефона

Обратите внимание: отправка номера телефона в чат-бот описана на странице API

window.WebApp.requestContact()

Запрашивает номер телефона пользователя в модальном окне нативного клиента MAX

Данные пользователя (включая номер телефона), полученные с помощью метода requestContact(), могут использоваться только для взаимодействия с текущим мини-приложением. Например, их можно применять для регистрации в программе лояльности, проверки статуса заказа, идентификации пользователя

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{
    phone: string;
    authDate: string; // timestamp создания hash
    hash: string;
}>

Проверка номера телефона

Для проверки, что полученный на запрос номер телефона совпадает с номером, привязанным к аккаунту пользователя в MAX, сравните:

Значение поля hash, полученное от клиента
Значение функции HMAC_SHA256(authDate + phone + userId, botToken), где:
- HMAC_SHA256 — стандартная для большинства языков программирования криптографическая функция
- authDate + phone + userId — параметры в алфавитном порядке, используемые для вычисления хеша: сформируйте строку, объединив пары key=value с разделителем \n
- botToken — токен бота, чьё мини-приложение запрашивает номер телефона пользователя

Если значения совпадают, это подтверждает, что пользователь поделился номером телефона, привязанным к его аккаунту в MAX

При вычислении хеша значение phone не должно содержать +: вместо +7********** используется 7**********

Возможные ошибки

Если пользователь отказывается поделиться номером телефона или запрос завершился ошибкой, возвращает:

JSON

Скопировать

{
    "error": {
        "code": "client.request_phone.<reason>"
    }
}

Номер ошибки	Возможное значение `reason`	Описание ошибки
01	`user_refused_provide_phone_number`	Пользователь отказался предоставить номер телефона
02	`request_error`	Ошибка при выполнении запроса (нет сети / не ответил backend)

Подтверждение закрытия мини-приложения

Обратите внимание, что методы из этой категории отправляют запрос приложению MAX в одностороннем порядке

window.WebApp.enableClosingConfirmation()

Включает предупреждение о риске потерять заполненные данные, если закрыть мини-приложение

Пример

JAVASCRIPT

Скопировать

window.WebApp.enableClosingConfirmation()

window.WebApp.disableClosingConfirmation()

Выключает предупреждение о риске потерять заполненные данные, если закрыть мини-приложение

Пример

JAVASCRIPT

Скопировать

window.WebApp.disableClosingConfirmation()

Открытие ссылок

Библиотека поддерживает два формата открытия ссылок:

во внешнем браузере
в виде диплинка, связанного с max.ru

window.WebApp.openLink(url)

Открывает ссылку во внешнем браузере

Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, перехода по ссылке не будет

Типы данных и пример

Тип передаваемых данных

Пример

JAVASCRIPT

Скопировать

// URL веб-страницы, которую нужно открыть
url: string

window.WebApp.openMaxLink(url)

Открывает диплинк вида https://max.ru/<some-url> из мини-приложения внутри MAX. Если передать ссылку другого вида, метод откроет её во внешнем браузере

Типы данных и пример

Тип передаваемых данных

Пример

JAVASCRIPT

Скопировать

// Диплинк для клиента MAX
url: string

Скачивание файла

Условие для скачивания файла:

Наличие защищённого https-соединения, http-ссылки не работают
Перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, файл не будет скачан
Скачивание должно происходить в мини-приложении, открытом в мессенджере MAX. В браузере метод не работает

Скачивание файла через href не поддерживается — используйте только метод window.WebApp.downloadFile(url, file_name)

window.WebApp.downloadFile(url, file_name)

Скачивает файл по переданной https-ссылке под нужным названием

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

url: string // URL для скачивания файла — любой прямой хост: свой сервер, S3, CDN
file_name: string // Название файла при сохранении

Коды ошибок

Код ошибки	Описание
`client.download_file.invalid_params`	Невалидный URL или параметры
`client.download_file.request_timeout`	Превышен тайм-аут — нативный клиент не ответил за 60 сек

Шеринг контента

В библиотеке есть два способа для шеринга контента:

во внешние приложения
внутри MAX

window.WebApp.shareContent(params)

Вызывает нативный экран шеринга из мини-приложения на iOS, Android. Передаются параметры text и/или link: один из параметров всегда должен быть передан. Разделение является условным и сделано для удобства восприятия: если передать и текст, и ссылку в одном поле text, то результат не изменится

Этот метод не поддерживается веб-приложением

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

params: {
    text?: string;
    link?: string
}

window.WebApp.shareMaxContent(params)

Открывает экран шеринга внутри MAX

Чтобы обезопасить процесс, перед вызовом метода MAX Bridge проверяет клик пользователя в мини-приложении. Если клика не было, экран шеринга не откроется

Метод предоставляет возможность шеринга контента из мини-приложения в диалоги или групповые чаты MAX. Метод работает в двух режимах:

шеринг текста, который аналогичен WebApp.shareContent(params)
шеринг текста с контентом: файл, медиа

Для шеринга файла или медиа бот, на котором работает мини-приложение, предварительно отправляет контент пользователю через POST/messages. Шеринг медиа работает как пересылка сообщения, поэтому поддерживается любой тип контента:

Бот отправляет контент пользователю, например медиафайл или открытку
Мини-приложение получает идентификатор этого сообщения mid. Его возвращает MAX Bot API, когда сообщение отправляется пользователю
В мини-приложении вызывается shareMaxContent({ mid, chatType }), где mid — идентификатор сообщения от бота, а chatType — тип чата, сообщением из которого нужно поделиться:
- DIALOG — для диалога, личного чата между двумя пользователями
- CHAT — для группового чата. Пользователь должен быть участником чата
Пользователь выбирает, куда отправить контент — сообщение пересылается в выбранный чат

В метод передаются либо text и/или link, либо mid и chatType. Если при шеринге медиа или файла передать text или link, они будут проигнорированы

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

params: {
    text?: string;
    link?: string
} | {
    mid: string;
    chatType: 'DIALOG' | 'CHAT'
}

Сканирование QR-кодов

Библиотекой предусмотрено два режима работы:

сканирование QR-кода камерой
выбор файла для сканирования из файловой системы

По умолчанию установлен режим выбора файла из системы

window.WebApp.openCodeReader(fileSelect = true)

Открывает камеру для считывания QR-кода

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

// Использовать файл из системы или сканировать камерой
fileSelect: boolean

Вернётся результат в виде строки, если QR-код был найден и распознан

fileSelect = true — доступен также выбор из галереи
fileSelect = false — доступно сканирование только через камеру

Если fileSelect не передан, то по умолчанию считается fileSelect = true

Управление кнопкой «Назад» в шапке приложения

Управление кнопкой Назад происходит через объект BackButton

window.WebApp.BackButton.show()

Делает кнопку Назад активной и видимой

Пример

JAVASCRIPT

Скопировать

window.WebApp.BackButton.show()

window.WebApp.BackButton.hide()

Скрывает кнопку Назад

Пример

JAVASCRIPT

Скопировать

window.WebApp.BackButton.hide()

window.WebApp.BackButton.isVisible

Управляет отображением кнопки Назад в заголовке мини-приложения в интерфейсе MAX

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Значение false задано по умолчанию

window.WebApp.BackButton.onClick(callback)

Устанавливает обработчик событий нажатия на кнопку Назад

Чтобы оставить возможность отписки от события нажатия на кнопку, сохраните ссылку на функцию, которая будет передана в качестве callback

Типы данных и пример

Тип передаваемых данных

Пример

JAVASCRIPT

Скопировать

callback: () => void

window.WebApp.BackButton.offClick(callback)

Отключает обработчик событий нажатия кнопки Назад

Типы данных и пример

Тип передаваемых данных

Пример

JAVASCRIPT

Скопировать

callback: () => void

Хранилище устройства

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

Методы этого объекта не поддерживаются веб-приложением

window.WebApp.DeviceStorage.setItem(key, value)

Сохраняет переданную пару «ключ-значение» в локальном хранилище устройства для этого мини-приложения

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string
value: string

window.WebApp.DeviceStorage.getItem(key)

Получает значение из локального хранилища устройства по указанному ключу

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string

window.WebApp.DeviceStorage.removeItem(key)

Удаляет значение из локального хранилища устройства по указанному ключу

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string

window.WebApp.DeviceStorage.clear()

Очищает все ключи, ранее сохранённые ботом в локальном хранилище устройства

Пример

JAVASCRIPT

Скопировать

// Хранилище очищено
window.WebApp.DeviceStorage.clear();

Защищённое хранилище устройства

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

Защищённое хранилище подходит для хранения токенов, секретов, состояния аутентификации и другой конфиденциальной пользовательской информации. Каждый бот может хранить до 10 ключей на пользователя

Методы этого объекта не поддерживаются веб-приложением

window.WebApp.SecureStorage.setItem(key, value)

Сохраняет переданную пару «ключ-значение» в защищённом хранилище устройства

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string
value: string

window.WebApp.SecureStorage.getItem(key)

Получает значение из защищённого хранилища устройства по указанному ключу

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string

window.WebApp.SecureStorage.removeItem(key)

Удаляет значение из защищённого хранилища устройства по указанному ключу

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

key: string

window.WebApp.SecureStorage.clear()

Очищает все ключи, ранее сохранённые в защищённом хранилище устройства

Пример

JAVASCRIPT

Скопировать

// Хранилище очищено
window.WebApp.SecureStorage.clear();

Использование биометрии

Работа с биометрией доступна через объект BiometricManager. Он нужен для аутентификации, когда доступ к данным в keychain получается через биометрические идентификаторы

Методы этого объекта не поддерживаются десктоп- и веб-клиентом

window.WebApp.BiometricManager.init()

Перед использованием методов объекта BiometricManager нужно однократно вызвать метод первичной инициализации биометрии — init:

Проверяет наличие функции биометрии на устройстве
Проверяет, предоставлен ли доступ к биометрии на устройстве

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

type BiometryType = 'finger' | 'face' | 'unknown';

interface BiometryInfo {
    available: boolean;
    type: BiometryType[];
    accessRequested: boolean;
    accessGranted: boolean;
    tokenSaved: boolean;
    deviceId: string | null;
}

Promise<BiometryInfo>

Поле	Тип данных	Описание
`available`	`boolean`	Проверка доступности биометрии на устройстве пользователя, который запустил мини-приложение
`type`	`array`	Типы биометрии: `finger`, `face`, `unknown` Если пользователь отказался предоставить доступ к биометрии, то `biometricType= array<unknown>`. Для Android всегда `unknown`
`accessRequested`	`boolean`	Проверка отправки запроса на предоставление доступа к биометрии устройства Если пользователь отказался предоставить доступ к биометрии, то `accessRequested = false`
`accessGranted`	`boolean`	Проверка предоставления доступа к биометрии
`tokenSaved`	`boolean`	Проверка наличия токена авторизации через биометрию в безопасном хранилище устройства
`deviceId`	`string`	Идентификатор устройства — можно использовать для сопоставления токена с устройством

window.WebApp.BiometricManager.isInited

Получает состояние инициализации BiometricManager — была ли ранее первичная инициализация

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.BiometricManager.isBiometricAvailable

Проверяет доступность биометрии на устройстве пользователя, который запустил мини-приложение

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Если пользователь отказался предоставить доступ к биометрии, значение будет false

window.WebApp.BiometricManager.isAccessRequested

Проверяет, был ли ранее отправлен запрос на предоставление доступа к биометрии устройства

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Если пользователь отказался предоставить доступ к биометрии, значение будет false

window.WebApp.BiometricManager.isAccessGranted

Проверяет, предоставлен ли доступ к биометрии

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Если пользователь отказался предоставить доступ к биометрии, значение будет false

window.WebApp.BiometricManager.isBiometricTokenSaved

Проверяет наличие токена в безопасном хранилище устройства

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.BiometricManager.biometricType

Позволяет посмотреть доступные типы биометрии:

finger
face
unknown

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Array<'finger' | 'face' | 'unknown'>

Если пользователь отказался предоставить доступ к биометрии, то biometricType=["unknown"]

Для Android всегда ["unknown"]

window.WebApp.BiometricManager.deviceId

Возвращает идентификатор устройства — можно использовать для сопоставления токена с устройством

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

string | null

Возвращает null, если пользователь отказался предоставить доступ к биометрии

window.WebApp.BiometricManager.requestAccess(reason)

Отправляет запрос на доступ к использованию биометрии на устройстве

Возвращает тип данных BiometryInfo, подробнее — в подразделе про использование биометрии

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

// Причина запроса мини-приложения на использование доступа
// Размер: 1-128 символов, остальное будет отрезаться
// Необязательное поле
reason?: string

window.WebApp.BiometricManager.authenticate(reason)

Запускает процесс аутентификации при помощи биометрических данных

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

// Причина запроса мини-приложения на использование доступа
// Размер: 1-128 символов, остальное будет отрезаться
// Необязательное поле
reason?: string

window.WebApp.BiometricManager.updateBiometricToken(token, reason)

Обновляет биометрический токен в безопасном хранилище устройства

Для удаления токена вызовите метод без передачи параметра токена

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

token?: string
// Причина запроса мини-приложения на использование доступа
// Размер: 1-128 символов, остальное будет отрезаться
// Необязательное поле
reason?: string

window.WebApp.BiometricManager.openSettings()

Отображает нативное диалоговое окно с предложением перейти в настройки MAХ на экран приватности, чтобы дать доступ к биометрии устройства для мини-приложения

Вызывает закрытие мини-приложения

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{
    status: 'opened'
}>

Доступ к камере и микрофону

Пока функциональность доступна только на Android и в веб-клиенте — следите за обновлениями в мини-приложениях

Для работы с камерой и микрофоном используйте объект window.WebApp.PermissionsManager

Объект предназначен для управления доступами:

К камере — для съёмки фото и видео с возможностью выбора камеры (если их больше одной)
К микрофону — для записи аудио

Доступ к камере и микрофону позволяет использовать мини-приложения в МАХ, например, для проведения видео- и аудиотрансляций. МАХ не сохраняет данные видео- и аудиопотока. Данные обрабатываются самим мини-приложением, порядок обработки и хранения определяет владелец мини-приложения

Содержание подраздела:

Какие доступы должен предоставить пользователь мини-приложения
Общий сценарий получения доступа к аудио- и видеопотоку для всех платформ
Особенности сценария получения доступа к аудио- и видеопотоку для веб-платформы
Объект window.WebApp.PermissionsManager и общие методы
Методы проверки доступа МАХ к камере
Методы проверки доступа МАХ к микрофону

Какие доступы должен предоставить пользователь мини-приложения

Чтобы получить доступ к камере и микрофону, вам необходимо запросить, а пользователю — выдать:

Разрешение к этим функциям (обеим или по отдельности) на уровне MAX для конкретного мини-приложения. Для каждого мини-приложения нужно запрашивать отдельные доступы. Например, пользователь может разрешить доступ к камере одному мини-приложению и не разрешить другому
Разрешение на доступ МАХ к этим функциям (обеим или по отдельности) на уровне клиентского устройства: мини-приложение перенаправляет пользователя в системные настройки устройства или браузера (для веб) прямо из интерфейса МАХ

Для своего мини-приложения вы можете запросить доступ:

Одновременно и к камере, и к микрофону
Только к камере
Только к микрофону

Когда мини-приложение делает запрос к клиентскому устройству, пользователю отображается модальное окно с запросом соответствующего разрешения

Пользователь должен последовательно выдать доступ к камере и микрофону сначала самому мини-приложению (доступ на уровне МАХ), а затем — МАХ (доступ на уровне клиентского устройства)

Если мини-приложении ещё не получило ни одного доступа к камере и/или микрофону, эти настройки в интерфейсе МАХ не отображаются

Интерфейс доступа на уровне мини-приложения

Запрос на доступ мини-приложения к камере и микрофону

Запрос на доступ мини-приложения только к камере

Запрос на доступ мини-приложения только к микрофону

Интерфейс доступа на уровне клиентского устройства

Запрос к системе клиентского устройства на доступ МАХ к камере

Запрос к системе клиентского устройства на доступ МАХ к микрофону

Если пользователь выдал все необходимые разрешения, запрашивать их повторно не потребуется. Исключение — очистка данных кеша и переустановка приложения. В этом случае мини-приложению необходимо повторно запросить все необходимые доступы

Если пользователь не выдал доступы для работы аудио и видео на уровне мини-приложения, ему необходимо самостоятельно включить их в настройках МАХ

Если пользователь не выдал системные доступы МАХ, ему необходимо перейти в настройки своего устройства и разрешить МАХ доступ к камере и/или микрофону, а затем перейти в настройки безопасности своего профиля МАХ и выдать доступы уже конкретному мини-приложению

Пользователь в любой момент может отозвать и выдать доступ к камере и/или микрофону в настройках MAX

Как выдать или отозвать доступы для конкретного мини-приложения в настройках МАХ

Откройте МАХ и перейдите в его настройки — нажмите ⚙️
Выберите раздел Безопасность
Перейдите в Мини-приложения и выберите нужное
Включите или отключите доступ к камере и/или микрофону для выбранного приложения

Экран выключения доступа мини-приложения к камере и микрофону

Мини-приложению выданы доступы к камере и микрофону

Общий сценарий получения доступа к аудио- и видеопотоку для всех платформ

Пользователь открывает мини-приложение в MAX
Мини-приложение с помощью PermissionsManager.isInited проверяет, был ли инициализирован объект PermissionsManager:
- Если true, то переходит к следующему шагу: запросу доступа
- Если false, то инициализирует методом PermissionsManager.init()
Мини-приложение запрашивает доступ к камере и/или микрофону методом PermissionsManager.requestAccess()
MAX проверяет, были ли ранее выданы доступы именно этому мини-приложению на уровне МАХ:
- Если доступ мини-приложению уже выдавался ранее, переход к следующему шагу: проверке системных доступов
- Если доступ ранее был выдан, а затем отозван, пользователя нужно перенаправить в настройки мини-приложения MAX с помощью метода PermissionsManager.openMaxSettings()
- Если доступ не выдавался, МАХ отображает окно подтверждения доступа мини-приложения к камере и/или микрофону. Далее возможен один из сценариев:
  - Если пользователь не разрешает доступ, он будет перенаправлен в настройки мини-приложения в MAX с помощью метода PermissionsManager.openMaxSettings(). В случае отказа пользователя перейти в настройки, вернётся ошибка client.permissions_open_max_settings.refused. Пользователь будет перенаправлен в МАХ
  - Если пользователь разрешает доступ, мини-приложение переходит к следующему шагу: проверке системных доступов
MAX проверяет системное разрешение на доступ к камере и/или микрофону на уровне клиентского устройства или браузера (для веб)
- Если системное разрешение уже есть, мини-приложение сразу получит доступ к видео-, аудиопотоку
- Если системного разрешения нет, отображается системное окно доступа. Дальнейший сценарий зависит от действия пользователя:
  - В случае отказа отобразится системная ошибка
  - В случае согласия мини-приложение получит доступ к аудио- и видеопотоку

Особенности сценария получения доступа к аудио- и видеопотоку для веб-платформы

Веб-клиент не может контролировать разрешения браузера на отображение мини-приложения и МАХ

При первом запуске мини-приложение получает отказ в браузерных разрешениях. Чтобы получить разрешение, вызовите метод PermissionsManager.requestAccess() — пользователю будет предложено дать доступ к камере и/или микрофону. Дальнейший сценарий зависит от действий пользователя

Пользователь не предоставил доступа к камере и/или микрофону

В этом случае в ответе PermissionsManager.requestAccess() вернётся client.permissions_request_access.app_permission_denied. Чтобы отобразить пользователю предложение дать доступ мини-приложению в настройках МАХ, вызовите PermissionsManager.openMaxSettings()

Пользователь предоставил доступ к камере и/или микрофону в настройках МАХ

В этом случае веб-клиент перезагрузит мини-приложение. При перезапуске вызовите JavaScript-метод getUserMedia() для запроса у пользователя разрешения на использование камеры и микрофона. Если пользователь откажет в доступе или камера и микрофон окажутся недоступны, в ответ на getUserMedia() вернётся ошибка NotAllowedError или NotFoundError соответственно. МАХ проверит ответ на getUserMedia():

Если разрешение выдано, вернёт соответствующий ответ. Если разрешение на уровне МАХ есть, мини-приложение может запросить доступ к камере и/или микрофону на уровне браузера

Если пользователь откажется предоставить доступ на уровне браузера, вам необходимо попросить пользователя разрешить доступ в настройках браузера. Отдельного экрана с таким запросом МАХ не отображает

При каждом последующем запуске мини-приложения необходимо вызывать метод getUserMedia()

Объект window.WebApp.PermissionsManager и общие методы

Объект window.WebApp.PermissionsManager предназначен, чтобы управлять доступами к камере для съёмки фото и видео с возможностью выбора камеры (если их больше одной), а также к микрофону — для записи аудио

window.WebApp.PermissionsManager.init()

Чтобы начать использовать методы объекта PermissionsManager, необходимо сначала его инициализировать с помощью PermissionsManager.init(). Метод проверяет, какие доступы уже предоставлены. Входные параметры отсутствуют

Тип передаваемых данных

Код

Скопировать

function

window.WebApp.PermissionsManager.isInited

Чтобы начать использовать методы объекта PermissionsManager, необходимо сначала инициализировать его — PermissionsManager.init(). Свойство PermissionsManager.isInited показывает, была ли уже инициализация:

true — объект PermissionsManager уже инициализирован, запросите нужные доступы с помощью PermissionsManager.requestAccess()
false — объект PermissionsManager не инициализирован, вызовите PermissionsManager.init()

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.openMaxSettings()

При вызове пользователь получает предложение перейти в настройки управления мини-приложениями в МАХ. Если пользователь откажется, метод закроет мини-приложение. Если пользователь согласится, то перейдёт в настройки мини-приложений в МАХ, где может выбрать, какие доступы выдать. Входные параметры отсутствуют

Интерфейс настроек доступов для конкретного мини-приложения в МАХ

Тип передаваемых данных

Код

Скопировать

function

Возможные ошибки client.permissions_open_max_settings

Код ошибки	Описание ошибки `client.permissions_open_max_settings`
`01`	`refused` — пользователь отказался перейти в настройки МАХ
`02`	`not_found` — идентификатор сессии не совпадает с начальным. Может вернуться, например, если пользователь во время работы с одним мини-приложением, перейдёт на страницу, где размещено другое мини-приложение. В этом случае второе мини-приложение может попытаться считать данные первого. Начните сессию заново с помощью `PermissionsManager.init()`
`03`	`already_enabled` — у мини-приложения уже есть доступ к камере и/или микрофону на уровне МАХ. Проверьте наличие системного доступа клиентского устройства
`04`	`not_inited` — отсутствует инициализация. Вызовите метод `PermissionsManager.init()`, а затем повторите текущий запрос

window.WebApp.PermissionsManager.openSystemSettings()

При вызове пользователь получает предложение перейти в системные настройки клиентского устройства. Если пользователь откажется, метод закроет мини-приложение. Если пользователь согласится, то перейдёт в системные настройки своего устройства, где сможет выбрать, какие доступы выдать. Входные параметры отсутствуют

Тип передаваемых данных

Код

Скопировать

function

Возможные ошибки client.permissions_open_system_settings

Код ошибки	Описание ошибки `client.permissions_open_system_settings`
`01`	`refused` — пользователь отказался перейти в системные настройки клиентского устройства
`02`	`not_found` — идентификатор сессии не совпадает с начальным. Может вернуться, например, если пользователь во время работы с одним мини-приложением, перейдёт на страницу, где размещено другое мини-приложение. В этом случае второе мини-приложение может попытаться считать данные первого. Начните сессию заново с помощью `PermissionsManager.init()`
`03`	`already_enabled` — у МАХ уже есть системный доступ к камере и/или микрофону на уровне клиентского устройства
`04`	`not_inited` — отсутствует инициализация. Вызовите метод `PermissionsManager.init()`, а затем повторите текущий запрос

window.WebApp.PermissionsManager.requestAccess()

Метод запрашивает доступ у пользователя к микрофону и/или камере.Если пользователь не предоставит доступ, мини-приложение должно вызвать метод PermissionsManager.openMaxSettings(), чтобы отобразить пользователю предложение разрешить доступ в настройках МАХ

Чтобы запросить доступ к камере и/или микрофону, укажите в permissions хотя бы один из параметров: camera — для доступа к камере, mic — для доступа к микрофону

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

function

Возможные ошибки client.permissions_request_access

Код ошибки	Описание ошибки `client.permissions_request_access`
`01`	`camera_not_supported` — камера недоступна
`02`	`not_inited` — отсутствует инициализация. Вызовите метод `PermissionsManager.init()`, а затем повторите текущий запрос
`03`	`camera_system_permission_denied` — у МАХ нет системного доступа к камере на уровне клиентского устройства
`04`	`camera_app_permission_denied` — нет доступа к камере для конкретного мини-приложения на уровне МАХ
`05`	`not_found` — идентификатор сессии не совпадает с начальным. Может вернуться, например, если пользователь во время работы с одним мини-приложением, перейдёт на страницу, где размещено другое мини-приложение. В этом случае второе мини-приложение может попытаться считать данные первого. Начните сессию заново с помощью `PermissionsManager.init()`
`06`	`mic_not_supported` — микрофон недоступен
`07`	`mic_system_permission_denied` — у МАХ нет системного доступа к микрофону на уровне клиентского устройства
`08`	`mic_app_permission_denied` — нет доступа к микрофону для конкретного мини-приложения на уровне МАХ
`09`	`app_permission_denied` — пользователь отказался выдать мини-приложению доступ к камере и микрофону на уровне МАХ
`10`	`system_permission_denied` — пользователь оказался выдать МАХ системный доступ к камере и микрофону на уровне клиентского устройства

Методы проверки доступа МАХ к камере

Методы предназначены для проверки доступа МАХ к камере на уровне конкретного мини-приложения и клиентского устройства

window.WebApp.PermissionsManager.isCameraAvailable

Метод проверяет наличие камеры на клиентском устройстве. Возможные значения:

true — камера доступна
false — камера недоступна

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isCameraSystemAccessGranted

Метод проверяет, предоставлен ли МАХ системный доступ к камере на уровне клиентского устройства. Возможные значения:

false — пользователь отказался предоставить системный доступ к камере
true — системный доступ к камере есть

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isCameraSystemAccessRequested

Метод проверяет, был ли ранее отправлен запрос на предоставление мини-приложению системного доступа к камере на уровне МАХ. Возможные значения:

false — запроса ещё не было
true — запрос уже был отправлен ранее

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isCameraAppAccessGranted

Метод проверяет, предоставлен ли конкретному мини-приложению доступ к камере на уровне МАХ. Возможные значения:

false — пользователь отказался предоставить доступ
true — доступ есть

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isCameraAppAccessRequested

Метод проверяет, был ли ранее отправлен запрос на предоставление доступа конкретного мини-приложения к камере на уровне МАХ. Возможные значения:

false — запроса ещё не было
true — запрос уже был отправлен ранее

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Методы проверки доступа МАХ к микрофону

Методы предназначены для проверки доступа МАХ к микрофону на уровне конкретного мини-приложения и клиентского устройства

window.WebApp.PermissionsManager.isMicAvailable

Метод проверяет наличие микрофона на клиентском устройстве. Возможные значения:

true — микрофон доступен
false — микрофон недоступен

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isMicSystemAccessGranted

Метод проверяет, предоставлен ли МАХ системный доступ к микрофону на уровне клиентского устройства. Возможные значения:

false — пользователь отказался предоставить системный доступ к микрофону
true — системный доступ к микрофону есть

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isMicSystemAccessRequested

Метод проверяет, был ли ранее отправлен запрос на предоставление МАХ системного доступа к микрофону на уровне клиентского устройства. Возможные значения:

false — запроса ещё не было
true — запрос уже был отправлен ранее

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isMicAppAccessGranted

Метод проверяет, предоставлен ли конкретному мини-приложению доступ к микрофону на уровне МАХ. Возможные значения:

false — пользователь отказался предоставить доступ
true — доступ есть

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.PermissionsManager.isMicAppAccessRequested

Метод проверяет, был ли ранее отправлен запрос на предоставление доступа мини-приложению к микрофону на уровне МАХ. Возможные значения:

false — запроса ещё не было
true — запрос уже был отправлен ранее

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

Пример реализации сценария получения доступа к камере

JAVASCRIPT

Скопировать

await window.WebApp.PermissionsManager.init()

try {
    // Запрос доступа к камере и микрофону 
    const info = await window.WebApp.PermissionsManager.requestAccess(
        ['camera', 'mic'],                  
        'Для запуска трансляции'
    )
    if (info.camera.appAccessGranted && info.camera.systemAccessGranted) {
        // Доступ к камере выдан на обоих уровнях: мини-приложения и клиентского устройства
    }
    const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })

} catch (error) {
    switch (error.error.code) {
        case 'client.permissions_request_access.camera_app_permission_denied':
        case 'client.permissions_request_access.app_permission_denied':
            // Отказ на уровне мини-приложения — ведём пользователя в настройки MAX
            await window.WebApp.PermissionsManager.openMaxSettings()
            break
        case 'client.permissions_request_access.camera_system_permission_denied':
        case 'client.permissions_request_access.system_permission_denied':
            // Отказ на системном уровне — ведём пользователя в настройки устройства
            await window.WebApp.PermissionsManager.openSystemSettings()
            break
        case 'client.permissions_request_access.not_inited':
            // Объект PermissionsManager не инициализирован — вызываем инициализацию
            await window.WebApp.PermissionsManager.init()
            break
    }
}

Тактильные отклики

Чтобы активировать и настроить тактильную обратную связь при взаимодействии пользователя с веб-приложением, используйте объект HapticFeedback

Методы этого объекта не поддерживаются десктоп- и веб-клиентом

window.WebApp.HapticFeedback.impactOccurred(impactStyle, disableVibrationFallback)

С помощью этого метода приложение MAX может воспроизвести соответствующие тактильные эффекты на основе переданного значения стиля

Подходит для тактильного отклика на интерактивные элементы, например при нажатии на кнопку

Стиль может иметь одно из следующих значений:

soft — мягкая вибрация
light — лёгкая вибрация
medium — средняя вибрация
heavy — сильная вибрация
rigid — жёсткая вибрация

disableVibrationFallback — разрешение использовать вибрацию с постоянной амплитудой на устройствах, которые не поддерживают вибрацию с переменной амплитудой. Значение по умолчанию: false

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

impactStyle: 'light' | 'medium' | 'heavy' | 'rigid' | 'soft'
disableVibrationFallback?: boolean // По умолчанию false

window.WebApp.HapticFeedback.notificationOccurred(notificationType, disableVibrationFallback)

Возвращает статус событий или действий: выполнены успешно, не удалось выполнить или выдано предупреждение

Приложение MAХ может воспроизводить соответствующие тактильные сигналы на основе переданного значения типа. Тип может быть одним из следующих значений:

error — не удалось выполнить
success — выполнены успешно
warning — выдано предупреждение

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

impactStyle: 'error' | 'success' | 'warning'
disableVibrationFallback?: boolean // По умолчанию false

window.WebApp.HapticFeedback.selectionChanged(disableVibrationFallback)

Сообщает, что пользователь изменил выбор

Приложение MAX может воспроизвести соответствующие тактильные сигналы

Не используйте эту обратную связь, когда пользователь делает или подтверждает выбор. Используйте её только при изменении выбора

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

// По умолчанию false
disableVibrationFallback?: boolean

NFC-модуль

Работа с NFC-модулем доступна через объект NfcManager

Методы этого объекта поддерживаются только для Android

Чтобы начать использовать методы объекта NfcManager, необходимо сначала вызвать его метод инициализации init

window.WebApp.NfcManager.init()

Инициализирует NfcManager

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

interface NfcInfo {
  available: boolean;
  enabled: boolean;
  accessRevoked?: boolean;
}

Описание свойств объекта

Поле	Тип данных	Описание
`available`	`boolean`	Проверка наличия NFC-модуля на устройстве пользователя
`enabled`	`boolean`	Проверка включения NFC-модуля в настройках системы
`accessRevoked?`	`boolean`	Отозвал ли пользователь разрешение использовать NFC-модуль для текущего мини-приложения в настройках приватности MAX

window.WebApp.NfcManager.isInited

Возвращает состояние инициализации NfcManager

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

boolean

window.WebApp.NfcManager.openSystemSettings()

Открывает страницу системных настроек доступа к NFC-модулю и вызывает закрытие мини-приложения

Если пользователь не отключал NFC-модуль, то переход не будет выполнен

Типы данных и пример

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

Promise<{
    status: 'opened'
}>

window.WebApp.NfcManager.emulateNfcTag(nfctag)

Запускает через NFC-модуль передачу данных, полученных из мини-приложения

Если не передать данные NFC-метки, то вещание будет остановлено

Типы данных и пример

Тип передаваемых данных

Тип возвращаемых данных

Пример

JAVASCRIPT

Скопировать

nfctag?: 'string'

Ошибки и обработка исключений

Большинство методов возвращают Promise-объекты, и в случае ошибки вызывается reject

Типы данных и пример

Структура объекта ошибки

Пример

JAVASCRIPT

Скопировать

{
    error: {
        code: string
    }
}