Мета-параметри й зворотні виклики
Метапараметри — це довільно визначувані пари ключ-значення, які ви передаєте під час створення зустрічі. Вони дають змогу додавати власні метадані, запускати автоматизовані callback-и для певних подій, керувати анонімізацією запису та документувати походження зустрічі для інтеграцій LMS.
Як працюють метапараметри
Мета-параметри передаються у виклику API create з використанням правила іменування meta_. Ви можете додати будь-яку кількість метапараметрів до однієї зустрічі.
create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum- Мета-параметри повертаються у відповідях
getMeetingInfoіgetRecordings. - Записи можна фільтрувати за метазначеннями за допомогою
getRecordings?meta_.= - Метадані записів можна оновити пізніше через
updateRecordings.
Мета-параметри callback-викликів
Деякі метапараметри мають особливе значення та запускають callback-и HTTP, коли відбуваються певні події. Це дає вашому застосунку змогу автоматично реагувати на події життєвого циклу зустрічі.
meta_endCallbackUrl
Запускає запит HTTP GET на вказану URL-адресу, коли зустріч завершується.
meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended| Властивість | Значення |
|---|---|
| Метод HTTP | GET |
| Тригер | Коли зустріч завершується |
| Параметри Callback | meetingID — ідентифікатор зустрічіrecordingmarks — true якщо запис містить позначки, інакше false |
Приклад запиту зворотного виклику:
GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=truemeta_bbb-recording-ready-url
Запускає запит HTTP POST, коли запис було повністю оброблено та опубліковано.
meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready| Властивість | Значення |
|---|---|
| Метод HTTP | POST |
| Тригер | Коли запис повністю оброблено та опубліковано |
| Безпека | Параметри підписані через JWT (JSON Web Token) |
| Тіло POST | Містить підписані дані з інформацією про запис |
Не плутайте цей callback із endCallbackUrl. Обробка запису може зайняти значний час після завершення зустрічі. Callback recording-ready спрацьовує лише після завершення обробки.
meta_analytics-callback-url
Запускає запит HTTP POST з агрегованими аналітичними даними після завершення зустрічі.
meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics| Властивість | Значення |
|---|---|
| Метод HTTP | POST |
| Тригер | Після завершення зустрічі (post-events hook) |
| Автентифікація | Токен JWT, надісланий як заголовок Authorization: Bearer (HS512, підписаний спільним секретом BBB, дійсний 24 години) |
| Формат тіла | Об’єкт JSON, що містить version, meeting_id, internal_meeting_id, data |
| Вміст даних | Тривалість участі, статистика активності, використання чату та інші агреговані події зустрічі |
URL callback-у аналітики береться з кодової бази BigBlueButton і не повністю задокументована в офіційній документації API. Точна схема об’єкта аналітичних даних не стандартизована й може змінюватися між версіями. undocumented
Зверніть увагу на різницю в доставці JWT: analytics-callback-url надсилає JWT як заголовок HTTP Authorization, тоді як bbb-recording-ready-url включає JWT безпосередньо в тіло POST.
Параметри анонімізації запису
Ці метапараметри визначають, чи будуть анонімізовані імена відправників чату в оброблених записах. Вони корисні для дотримання вимог конфіденційності та захисту даних.
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
meta_bbb-anonymize-chat | Boolean | false | Анонімізує відправників повідомлень чату в оброблених записах. Впливає лише на повідомлення глядачів (немодераторів). Імена модераторів залишаються видимими. |
meta_bbb-anonymize-chat-moderators | Boolean | false | Додатково анонімізує відправників повідомлень чату модераторів у записах. Зазвичай також потрібно встановити meta_bbb-anonymize-chat=true. |
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksumПараметри анонімізації лише коротко згадуються в офіційній документації API. Їхня поведінка виведена з вихідного коду BigBlueButton. undocumented
Параметри інтеграції LMS
Багато плагінів LMS автоматично встановлюють метапараметри, щоб документувати походження зустрічі. Вони мають інформаційний характер і не впливають на поведінку зустрічі, але корисні для аудиту та звітності.
| Параметр | Приклад | Опис |
|---|---|---|
meta_bbb-origin | greenlight, moodle | Вихідний застосунок, який створив зустріч. |
meta_bbb-origin-version | v3.1.0 | Версія вихідного застосунку. |
meta_bbb-origin-server-name | api-guide.bbbserver.com | Ім’я хоста вихідного застосунку. |
meta_bbb-context | Course: Computer Science | Контекстна інформація, наприклад назва курсу. |
meta_bbb-context-id | course-42 | Ідентифікатор контексту для програмного використання. |
Найкращі практики для користувацьких метапараметрів
- Використовуйте описові назви ключів (наприклад,
meta_department,meta_project), які чітко вказують на призначення значення. - Кодуйте значення у форматі URL, якщо вони містять спеціальні символи, пробіли або символи поза ASCII.
- Використовуйте метапараметри для інтеграції із зовнішніми системами, такими як CRMs, навчальні платформи або аналітичні панелі.
- Оновлюйте метадані запису постфактум за допомогою ендпоінта
updateRecordings, щоб додати або виправити метадані.
Поєднуйте метапараметри з фільтрацією getRecordings, щоб створювати потужні процеси пошуку та категоризації ваших записів. Наприклад, фільтруйте за meta_department=engineering, щоб отримати лише записи інженерних зустрічей.