Глава 19

userdata – Настройки клиента

Параметры userdata позволяют переопределять клиентские настройки для каждого пользователя отдельно, добавляя к вызову API userdata- параметры с префиксом join. Это позволяет настраивать работу BigBlueButton для отдельных участников без изменения конфигурации сервера.

Список доступных параметров userdata лишь частично описан в официальной документации BigBlueButton. Многие параметры получены на основе анализа исходного кода settings.yml и могут изменяться между версиями без предупреждения. undocumented

Как работают параметры 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-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_auto_swap_layout Boolean — Автоматически переключать макет, когда демонстрируется презентация.
userdata-bbb_default_layout String — Установить макет по умолчанию для пользователя. Доступные значения зависят от конфигурации клиента. undocumented
userdata-bbb_hide_presentation Boolean — Скрыть область презентации от пользователя.
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 может использоваться для cross-site scripting, если URL join создаются на стороне клиента. Всегда генерируйте URL join на сервере, где вы контролируете значения параметров.

Параметры элементов интерфейса

Параметр Тип По умолчанию Описание
userdata-bbb_hide_notifications Boolean — Скрыть всплывающие уведомления в интерфейсе клиента.
userdata-bbb_hide_controls Boolean — Скрыть элементы управления интерфейса (кнопки панели инструментов) от пользователя.
userdata-bbb_shortcuts String — Определить пользовательские сочетания клавиш для пользователя.

Параметры записи и внешнего управления

Параметр Тип По умолчанию Описание
userdata-bbb_outside_toggle_recording Boolean — Разрешить внешнему приложению включать и выключать запись встречи.
userdata-bbb_outside_toggle_self_voice Boolean — Разрешить внешнему приложению включать и выключать аудио пользователя.

Параметры доски

Параметр Тип По умолчанию Описание
userdata-bbb_initial_selected_tool String — Задать изначально выбранный инструмент доски, когда пользователь открывает доску. Допустимые значения определяются конфигурацией клиента. undocumented

Практические примеры

Ниже приведены распространённые комбинации параметров 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 независимо от этой настройки.

Официальная документация охватывает лишь часть. Наиболее полный и актуальный список находится в файле settings.yml в исходном коде клиента BigBlueButton. Новые параметры часто добавляются без обновления документации.
Руководство по API BigBlueButton