Глава 21

Советы, лучшие практики и скрытые возможности

В этой главе собраны малоизвестные возможности API, рекомендации по безопасности и проверенные лучшие практики интеграции с API BigBlueButton. Многие из этих деталей лишь частично задокументированы в официальных источниках и были подтверждены анализом исходного кода и исследованиями сообщества.

Скрытое значение политики гостей

Помимо трёх хорошо известных значений параметра guestPolicy, существует четвёртое значение, которое редко документируется, но очень полезно для сценариев со смешанной аудиторией.

Значение Поведение
ALWAYS_ACCEPT Все пользователи присоединяются сразу без подтверждения.
ALWAYS_DENY Только модераторы могут присоединиться ко встрече.
ASK_MODERATOR Гости ждут в лобби, пока модератор не одобрит их.
ALWAYS_ACCEPT_AUTH Аутентифицированные пользователи присоединяются напрямую. Только неаутентифицированные гости требуют одобрения модератора.

Политика ALWAYS_ACCEPT_AUTH идеально подходит, когда зарегистрированные пользователи из LMS должны присоединяться без ожидания, а внешние гости по-прежнему должны быть одобрены модератором.

Серверный callback с meetingEndedURL

Параметр meetingEndedURL предоставляет серверный callback, который в важных аспектах отличается от часто используемого meta_endCallbackUrl:

  • Он не передаётся клиенту и не сохраняется в записях.
  • Он используется внутренне такими системами, как Scalelite.
  • Он хорошо подходит для серверных интеграций, где URL обратного вызова должен оставаться скрытым.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Параметры захвата комнат для групповой работы

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

Параметр Тип Описание
breakoutRoomsCaptureSlides Boolean Импортировать слайды из комнат для групповой работы в основную встречу.
breakoutRoomsCaptureNotes Boolean Импортировать общие заметки из комнат для групповой работы в основную встречу.
breakoutRoomsCaptureNotesFilename String Пользовательское имя файла для захваченного файла заметок.

Параметры аннотаций и брендинга

Параметр lockSettingsHideViewersAnnotation скрывает аннотации на доске, сделанные другими зрителями, так что каждый участник видит только свои собственные аннотации и аннотации ведущего. 

create?meetingID=replace-with-meeting-id&lockSettingsHideViewersAnnotation=true&checksum=replace-with-checksum

Параметр copyright задаёт пользовательский текст авторских прав в клиенте BBB, что может быть полезно для white-label развертываний: 

create?meetingID=replace-with-meeting-id&copyright=Example+Organization&checksum=replace-with-checksum

Параметр logo работает только если displayBrandingArea=true задан в файле конфигурации сервера /etc/bigbluebutton/bbb-web.properties.

Лучшие практики безопасности

Всегда включайте createTime в URL присоединения

Всегда включайте значение createTime из ответа create в ваш URL join. Это предотвращает повторное использование старых ссылок join, когда создаётся новая встреча с тем же ID встречи. 

join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&createTime=1715261728123&checksum=replace-with-checksum

Вычисление checksum для запросов POST

Распространённая ошибка: checksum всегда вычисляется только из строки запроса URL, даже для запросов POST. Тело запроса (XML, JSON) никогда не включается в вычисление checksum. 

Checksum = SHA256("create" + "meetingID=replace-with-meeting-id&name=Demo" + "replace-with-secret")

Тело POST (например, XML презентации) отправляется отдельно, но не хешируется.

Прошлая уязвимость безопасности (CVE GHSA-4m48-49h7-f3c4) позволяла злоумышленникам с действительным URL присоединения внедрять дополнительные параметры в подписанные ссылки присоединения. Всегда проверяйте и очищайте все параметры на стороне сервера перед генерацией подписанных URL API.

BBB 3.0 Критические изменения

BigBlueButton 3.0 вводит несколько критических изменений, влияющих на интеграции API. Внимательно изучите следующую таблицу при обновлении:

Изменение Подробности
password → role Вызов join теперь использует role=MODERATOR или role=VIEWER вместо паролей.
POST удалён для /join Для вызовов GETjoin принимаются только запросы .
Content-Type обязательно Должен быть указан для всех запросов POST.
Принимаемый Content-Types для /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Удалённые параметры breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled были заменены параметром disabledFeatures.

Устаревшие эндпоинты

Следующие эндпоинты устарели и не должны использоваться в новых интеграциях:

Конечная точка Статус Замена
getDefaultConfigXML Устарел начиная с BBB 2.4, удалён в BBB 3.0. clientSettingsOverride
setConfigXML Устарел начиная с BBB 2.4, удалён в BBB 3.0. clientSettingsOverride

Поведение объединения манифестов плагинов

Манифесты плагинов из трёх источников объединяются (а не перезаписываются) при создании встречи:

  1. Конфигурация сервера
  2. Параметр pluginManifests в вызове create
  3. Параметр pluginManifestsFetchUrl

Дубликаты удаляются автоматически. Это обеспечивает гибкую конфигурацию плагинов на нескольких уровнях.

Важные параметры конфигурации сервера

Следующие настройки из bigbluebutton.properties нельзя контролировать через API, но они напрямую влияют на поведение API:

Свойство По умолчанию Описание
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Поддерживаемые алгоритмы контрольной суммы для аутентификации API.
maxUserConcurrentAccesses 3 Максимальное количество одновременных сессий на пользователя (по внешнему ID).
allowOverrideClientSettingsOnCreateCall false Включает параметр clientSettingsOverride в теле create.
allowRevealOfBBBVersion false Показывает версию BBB в ответе корня API.
allowFetchAllRecordings true Разрешает getRecordings без фильтра по ID встречи.
maxFileSizeUpload 30000000 Максимальный размер файла для загрузки презентаций (30 МБ).
defaultHttpSessionTimeout 14400 Тайм-аут HTTP-сессии в секундах (4 часа).
sessionsCleanupDelayInMinutes 60 Сессии остаются активными в течение этого количества минут после окончания встречи.
fetchUrlSupportedProtocols https Разрешённые протоколы для получения URL (например, загрузки презентаций).

Конфигурация Media Bridge

BigBlueButton 3.0 представляет LiveKit как альтернативный медиамост. Следующие параметры create определяют, какой мост будет использоваться:

Параметр Возможные значения По умолчанию
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Тайм-аут конвертации презентации

Начиная с BBB 3.0, серверный параметр maxPageConversionTime (по умолчанию: 60 секунд) ограничивает время преобразования на слайд. Сложные презентации с большим количеством страниц или тяжёлой графикой могут превысить этот тайм-аут, что приведёт к сбою преобразования слайдов.

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

Часто задаваемые вопросы

Это четвёртое, менее известное значение параметра guestPolicy. Аутентифицированные пользователи присоединяются сразу, тогда как неаутентифицированные гости должны ждать одобрения модератора. Это полезно, когда пользователи LMS должны входить напрямую, а внешние посетители — проходить проверку.

Параметр meetingEndedURL — это серверный callback, который никогда не раскрывается клиентам и не сохраняется в записях. Он предназначен для внутренних интеграций, где URL callback должен оставаться приватным, например в развертываниях Scalelite.

Нет. Checksum всегда вычисляется только из строки запроса URL. Тело POST (например, XML презентации) отправляется отдельно и не является частью хеша. Это распространённый источник ошибок для разработчиков, впервые работающих с API.

В BigBlueButton 3.0 параметр password для вызова join был заменён параметром role. Теперь вы передаёте role=MODERATOR или role=VIEWER вместо пароля участника или модератора.

Включение значения createTime из ответа create гарантирует, что старые ссылки присоединения нельзя будет повторно использовать для новой встречи, созданной с тем же meeting ID. Это важный механизм безопасности, предотвращающий несанкционированный доступ через устаревшие URL.

Оба эндпоинта были объявлены устаревшими в BBB 2.4 и удалены в BBB 3.0. Они были заменены параметром clientSettingsOverride в вызове create, который предоставляет более гибкий способ настройки поведения клиента для каждой встречи.
Руководство по API BigBlueButton