Розділ 21

Поради, найкращі практики та приховані можливості

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

Приховане значення політики гостей

Окрім трьох добре відомих значень параметра guestPolicy, існує четверте значення, яке рідко документується, але є дуже корисним для сценаріїв зі змішаною аудиторією.

Значення Поведінка
ALWAYS_ACCEPT Усі користувачі приєднуються одразу без схвалення.
ALWAYS_DENY Лише модератори можуть приєднатися до зустрічі.
ASK_MODERATOR Гості очікують у лобі, доки модератор їх не схвалить.
ALWAYS_ACCEPT_AUTH Автентифіковані користувачі приєднуються напряму. Лише неавтентифіковані гості потребують схвалення модератора.

Політика ALWAYS_ACCEPT_AUTH ідеально підходить, коли зареєстровані користувачі з LMS мають приєднуватися без очікування, тоді як зовнішні гості все ще потребують схвалення модератора.

Зворотний виклик на стороні сервера за допомогою meetingEndedURL

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

  • Він не розкривається клієнту і не зберігається в записах.
  • Він використовується внутрішньо такими системами, як Scalelite.
  • Він добре підходить для серверних інтеграцій, де URL-адреса callback має залишатися прихованою.
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. Це запобігає повторному використанню старих посилань приєднання, коли створюється нова зустріч з тим самим ID зустрічі. 

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

Обчислення контрольної суми для запитів POST

Поширена помилка: контрольна сума завжди обчислюється лише з рядка запиту URL, навіть для запитів POST. Тіло запиту (XML, JSON) ніколи не включається в обчислення контрольної суми. 

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 — це зворотний виклик на стороні сервера, який ніколи не показується клієнтам і не зберігається в записах. Його призначено для внутрішніх інтеграцій, де URL-адреса зворотного виклику має залишатися приватною, наприклад у розгортаннях Scalelite.

Ні. Контрольна сума завжди обчислюється лише з рядка запиту URL. Тіло POST (наприклад, презентація XML) надсилається окремо і не є частиною хешу. Це поширене джерело помилок для розробників, які лише починають працювати з API.

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

Включення значення createTime із відповіді create гарантує, що старі посилання приєднання не можна буде повторно використати для нової зустрічі, створеної з тим самим ID зустрічі. Це важливий механізм безпеки, який запобігає несанкціонованому доступу через застарілі URL-адреси.

Обидві кінцеві точки були позначені як застарілі в BBB 2.4 і вилучені в BBB 3.0. Їх було замінено параметром clientSettingsOverride у виклику create, який забезпечує гнучкіший спосіб налаштування поведінки клієнта для кожної зустрічі.
Посібник з API BigBlueButton