Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.
userdata – Настройки клиента
Параметры userdata позволяют переопределять клиентские настройки для каждого пользователя отдельно, добавляя к вызову API userdata- параметры с префиксом join. Это позволяет настраивать работу BigBlueButton для отдельных участников без изменения конфигурации сервера.
В BigBlueButton 3.0 параметры userdata перечислены не в справочнике API, а в руководстве администратора (Customize, раздел «Passing user metadata to the client on join»). Параметры могут изменяться между версиями без предупреждения.
Как работают параметры userdata
Параметры userdata передаются как параметры строки запроса URL в запросе join. Они переопределяют значения по умолчанию из settings.yml только для этой одной пользовательской сессии. Имена параметров всегда начинаются с префикса userdata-, за которым следует ключ настройки.
GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&userdata-bbb_auto_join_audio=true&userdata-bbb_skip_check_audio=true&checksum=replace-with-checksum Поскольку параметры userdata являются частью строки запроса, они включаются в вычисление checksum. Обязательно добавляйте их до вычисления checksum, а не после.
Часть после userdata- не должна содержать ещё один дефис — иначе параметр отбрасывается. Префикс userdata-bbb_ зарезервирован для BigBlueButton; интеграции, добавляющие собственные данные для отдельных пользователей, должны использовать свой префикс, например userdata-myapp_cohort=2026A. Такие параметры сохраняются вместе с данными пользователя и включаются в события записи, но игнорируются клиентом.
Параметры аудио и медиа
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_auto_join_audio | Boolean | — | Автоматически подключать пользователя к аудиомосту при входе во встречу. |
userdata-bbb_listen_only_mode | Boolean | — | Включить или отключить режим listen-only для пользователя. |
userdata-bbb_force_listen_only | Boolean | — | Принудительно перевести пользователя в режим listen-only. Это не относится к модераторам. |
userdata-bbb_skip_check_audio | Boolean | — | Пропустить диалог проверки аудио при входе. |
userdata-bbb_skip_echotest_if_previous_device | Boolean | — | Пропустить echo test, если обнаружено то же аудиоустройство, что и в предыдущей сессии. |
Параметры веб-камеры
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_auto_share_webcam | Boolean | — | Автоматически начинать трансляцию веб-камеры, когда пользователь присоединяется. |
userdata-bbb_mirror_own_webcam | Boolean | — | Отражать собственное превью веб-камеры пользователя по горизонтали. |
Параметры макета и отображения
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_default_layout | String | — | Макет, с которым запускается клиент. enforceLayout в join имеет приоритет; если ни один из вариантов не задан, используется макет конференции. Принимает те же значения, что и meetingLayout в create. BBB 3.0+ |
userdata-bbb_change_layout Removed in 4.0 | String | — | Устаревший переключатель макета. Принимает те же значения, что и meetingLayout в create (например, SMART_LAYOUT), и имеет приоритет над userdata-bbb_default_layout. Вместо него используйте userdata-bbb_default_layout. |
userdata-bbb_hide_presentation_on_join | Boolean | false | Запускать со свёрнутой областью презентации; пользователь может развернуть её. BBB 2.6+ |
userdata-bbb_prefer_dark_theme | Boolean | — | Активировать тёмную тему интерфейса. |
Параметры кастомизации и брендинга
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_custom_style | String | — | Встроенные правила CSS (URL-кодированные), применяемые к клиенту BigBlueButton для этого пользователя. |
userdata-bbb_custom_style_url | URL | — | URL внешнего файла CSS, загружаемого клиентом для пользовательского оформления. Должен обслуживаться по HTTPS. |
Параметр userdata-bbb_custom_style может использоваться для CSS injection, если URL join создаются на стороне клиента. Всегда генерируйте URL join на сервере, где вы контролируете значения параметров.
Параметры элементов интерфейса
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_hide_notifications | Boolean | — | Скрыть всплывающие уведомления в интерфейсе клиента. |
userdata-bbb_hide_controls | Boolean | — | Скрыть элементы управления интерфейса (кнопки панели инструментов) от пользователя. |
userdata-bbb_shortcuts | String | — | JSON-массив сочетаний клавиш, которые остаются включёнными (например, ["toggleMute","raiseHand"]); пустой массив отключает все сочетания клавиш. |
userdata-enable-user-reaction Removed in 4.0 | Boolean | — | Считывается клиентом, но bbb-web отбрасывает каждый параметр userdata-, ключ которого содержит дефис, поэтому этот параметр никогда не доходит до клиента и не оказывает никакого эффекта. Вместо этого используйте значение userReactions параметра disabledFeatures. |
Параметры доски
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
userdata-bbb_initial_selected_tool | String | — | Задать изначально выбранный инструмент доски, когда пользователь открывает доску. Допустимые значения определяются конфигурацией клиента. |
Практические примеры
Ниже приведены распространённые комбинации параметров userdata для типичных сценариев использования.
Режим киоска
Идеально подходит для экранов в конференц-залах или цифровых вывесок, где взаимодействие с пользователем не требуется:
userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true Брендинг для конкретного арендатора
Примените пользовательскую таблицу стилей CSS для каждого арендатора или клиента:
userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css Доступное быстрое присоединение
Упростите процесс присоединения для пользователей, которым нужен упрощённый и доступный интерфейс:
userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true Важные примечания
- Параметры userdata влияют только на текущую сессию отдельного пользователя. Они не изменяют настройки сервера по умолчанию.
- Не все параметры доступны в каждой версии BigBlueButton. Перед развертыванием протестируйте их на вашей целевой версии.
- CSS, загружаемый через
userdata-bbb_custom_style_url, должен обслуживаться по HTTPS.
При использовании эндпоинта getJoinUrl некоторые параметры userdata блокируются для зрителей (роль VIEWER) в качестве меры безопасности. Список блокировки настраивается на стороне сервера через свойство getJoinUrlUserdataBlocklist в bigbluebutton.properties. Это не позволяет зрителям переопределять критически важные настройки клиента через предварительно подписанные URL join. В сессионных залах список блокировки распространяется и на модераторов. undocumented
Часто задаваемые вопросы
userdata-bbb_force_listen_only применяется только к зрителям. Модераторы не переводятся принудительно в режим listen-only независимо от этой настройки.getFromUserSettings в HTML5-клиенте).