Версия API: 4.x последняя 3.x

Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.

Глава 19

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

Нет. Параметры userdata предназначены только для эндпоинта join. Они обрабатываются клиентом, когда пользователь присоединяется к встрече, и не влияют на вызов create.

Да. Поскольку они являются частью строки запроса URL, они включаются в вычисление checksum. Вы должны добавить все параметры userdata в строку запроса до вычисления checksum.

Нет. Параметр userdata-bbb_force_listen_only применяется только к зрителям. Модераторы не переводятся принудительно в режим listen-only независимо от этой настройки.

В BigBlueButton 3.0 параметры, считываемые клиентом, перечислены в руководстве администратора (Customize, раздел «Passing user metadata to the client on join»). Окончательным источником информации является исходный код клиента (вызовы getFromUserSettings в HTML5-клиенте).
Руководство по API BigBlueButton