Kapitel 18

Meta-Parameter & Callbacks

Meta-Parameter sind frei definierbare Schlüssel-Wert-Paare, die Sie beim Erstellen eines Meetings übergeben. Sie ermöglichen es Ihnen, benutzerdefinierte Metadaten anzuhängen, automatisierte Callbacks bei bestimmten Ereignissen auszulösen, die Anonymisierung von Aufzeichnungen zu steuern und die Herkunft eines Meetings für LMS-Integrationen zu dokumentieren.

So funktionieren Meta-Parameter

Meta-Parameter werden im API-Aufruf create unter Verwendung der Namenskonvention meta_= übergeben. Sie können beliebig viele Meta-Parameter an ein einzelnes Meeting anhängen. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Meta-Parameter werden in den Antworten von getMeetingInfo und getRecordings zurückgegeben.
  • Aufzeichnungen können über Meta-Werte mit getRecordings?meta_= gefiltert werden.
  • Aufzeichnungsmetadaten können nachträglich über updateRecordings aktualisiert werden.

Callback-Meta-Parameter

Bestimmte Meta-Parameter haben eine besondere Bedeutung und lösen HTTP-Callbacks aus, wenn bestimmte Ereignisse eintreten. Diese ermöglichen es Ihrer Anwendung, automatisch auf Ereignisse im Meeting-Lebenszyklus zu reagieren.

meta_endCallbackUrl

Löst eine HTTP GET-Anfrage an die angegebene URL aus, wenn das Meeting endet. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Eigenschaft Wert
HTTP-Methode GET
Auslöser Wenn das Meeting endet
Callback Parameter meetingID — die Meeting-ID
recordingmarks — true wenn die Aufzeichnung Markierungen enthält, andernfalls false

Beispiel für eine Callback-Anfrage: 

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Löst eine HTTP POST-Anfrage aus, wenn die Aufzeichnung vollständig verarbeitet und veröffentlicht wurde. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Eigenschaft Wert
HTTP-Methode POST
Auslöser Wenn die Aufzeichnung vollständig verarbeitet und veröffentlicht wurde
Sicherheit Parameter sind JWT-signiert (JSON Web Token)
POST-Body Enthält signierte Daten mit Informationen zur Aufzeichnung

Verwechseln Sie diesen Callback nicht mit endCallbackUrl. Die Verarbeitung von Aufzeichnungen kann nach dem Ende des Meetings erheblich Zeit in Anspruch nehmen. Der recording-ready-Callback wird erst ausgelöst, wenn die Verarbeitung abgeschlossen ist.

meta_analytics-callback-url

Löst nach dem Ende des Meetings eine HTTP POST-Anfrage mit aggregierten Analysedaten aus. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Eigenschaft Wert
HTTP-Methode POST
Auslöser Nach dem Ende des Meetings (post-events hook)
Authentifizierung Als JWT-Header gesendetes Authorization: Bearer-Token (HS512, mit dem gemeinsamen BBB-Secret signiert, 24 Stunden gültig)
Body-Format JSON-Objekt mit version, meeting_id, internal_meeting_id, data
Dateninhalt Teilnahmedauer, Aktivitätsstatistiken, Chat-Nutzung und andere aggregierte Meeting-Ereignisse

Die URL für den Analytics-Callback stammt aus der BigBlueButton-Codebasis und ist in der offiziellen API-Dokumentation nicht vollständig dokumentiert. Das genaue Schema des Analytics-Datenobjekts ist nicht standardisiert und kann sich zwischen Versionen ändern. undocumented

Beachten Sie den Unterschied bei der Zustellung von JWT: analytics-callback-url sendet das JWT als HTTP Authorization-Header, während bbb-recording-ready-url das JWT direkt im POST-Body enthält.

Parameter zur Anonymisierung von Aufzeichnungen

Diese Meta-Parameter steuern, ob die Namen der Chat-Absender in verarbeiteten Aufzeichnungen anonymisiert werden. Sie sind nützlich für Datenschutz-Compliance und Anforderungen an den Datenschutz.

Parameter Typ Standard Beschreibung
meta_bbb-anonymize-chat Boolean false Anonymisiert Chat-Nachrichten-Absender in verarbeiteten Aufzeichnungen. Betrifft nur Nachrichten von Zuschauern (keine Moderatoren). Namen von Moderatoren bleiben sichtbar.
meta_bbb-anonymize-chat-moderators Boolean false Anonymisiert zusätzlich die Absender von Moderator-Chat-Nachrichten in Aufzeichnungen. Erfordert in der Regel, dass meta_bbb-anonymize-chat=true ebenfalls gesetzt ist.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

Die Anonymisierungsparameter werden in der offiziellen API-Dokumentation nur kurz erwähnt. Ihr Verhalten wird aus dem BigBlueButton-Quellcode abgeleitet. undocumented

LMS-Integrationsparameter

Viele LMS-Plugins setzen automatisch Meta-Parameter, um die Herkunft eines Meetings zu dokumentieren. Diese dienen nur zur Information und beeinflussen das Verhalten des Meetings nicht, sind aber für Audits und Berichte nützlich.

Parameter Beispiel Beschreibung
meta_bbb-origin greenlight, moodle Die Quellanwendung, die das Meeting erstellt hat.
meta_bbb-origin-version v3.1.0 Version der Quellanwendung.
meta_bbb-origin-server-name api-guide.bbbserver.com Hostname der Quellanwendung.
meta_bbb-context Course: Computer Science Kontextinformationen wie z. B. der Kursname.
meta_bbb-context-id course-42 Kontextbezeichner für die programmatische Verwendung.

Best Practices für benutzerdefinierte Meta-Parameter

  • Verwenden Sie aussagekräftige Schlüsselnamen (z. B. meta_department, meta_project), die den Zweck des Werts klar erkennen lassen.
  • URL-kodieren Sie Werte, die Sonderzeichen, Leerzeichen oder Nicht-ASCII-Zeichen enthalten.
  • Verwenden Sie Meta-Parameter für die Integration mit externen Systemen wie CRMs, Lernplattformen oder Analytics-Dashboards.
  • Aktualisieren Sie Aufzeichnungsmetadaten nachträglich über den Endpunkt updateRecordings, um Metadaten hinzuzufügen oder zu korrigieren.

Kombinieren Sie Meta-Parameter mit der Filterung von getRecordings, um leistungsstarke Such- und Kategorisierungs-Workflows für Ihre Aufzeichnungen zu erstellen. Filtern Sie zum Beispiel nach meta_department=engineering, um nur Aufzeichnungen aus Engineering-Meetings abzurufen.

Häufig gestellte Fragen

Es gibt keine feste Obergrenze für die Anzahl der Meta-Parameter. Da sie jedoch als URL-Abfrageparameter übergeben werden, sollten Sie innerhalb praktikabler URL-Längenbeschränkungen bleiben (typischerweise 2.000 bis 8.000 Zeichen, abhängig von der Konfiguration des Webservers).

Meta-Parameter, die während des create-Aufrufs gesetzt werden, können nicht geändert werden, während das Meeting läuft. Metadaten von Aufzeichnungen können jedoch nach der Verarbeitung über den Endpunkt updateRecordings aktualisiert werden.

Der endCallbackUrl wird unmittelbar beim Ende des Meetings mit einer einfachen GET-Anfrage ausgelöst. Der bbb-recording-ready-url wird deutlich später ausgelöst, erst nachdem die Aufzeichnung vollständig verarbeitet und veröffentlicht wurde, und verwendet eine JWT-signierte POST-Anfrage.

Die Details zur JWT-Signierung sind in der offiziellen Dokumentation nicht vollständig spezifiziert. Basierend auf dem BigBlueButton-Quellcode wird das JWT mit dem gemeinsamen Server-Secret signiert. Die genauen Claims und der Algorithmus sollten gegen Ihre spezifische BigBlueButton-Version geprüft werden.

Die meisten Meta-Parameter dienen rein informativen Zwecken und ändern nicht, wie das Meeting funktioniert. Ausnahmen sind Callback-URLs, die bei Ereignissen HTTP-Anfragen auslösen, sowie Anonymisierungsparameter, die beeinflussen, wie Aufzeichnungen verarbeitet werden.

Ja. Schlüssel von Meta-Parametern werden als groß-/kleinschreibungssensitive Zeichenfolgen behandelt. Zum Beispiel würden meta_Department und meta_department als zwei separate Parameter gespeichert. Verwenden Sie in Ihrer Integration eine konsistente Groß- und Kleinschreibung, um Duplikate zu vermeiden.