Von 3.x auf 4.x migrieren
BigBlueButton 4.0 entfernt eine Reihe veralteter Parameter und Layoutwerte, ändert mehrere Standardwerte und führt neue Fehlerschlüssel ein. Dieser Leitfaden listet alles auf, was Sie in Ihren API-Aufrufen prüfen müssen, wenn Ihre Integration mit einem BigBlueButton 4.x-Server statt mit einem BigBlueButton 3.x-Server kommuniziert.
Geltungsbereich: Dieser Leitfaden behandelt die Änderungen an API-Aufrufen Ihrer Anwendung (create, join, insertDocument, …). Er behandelt nicht die Aktualisierung oder Migration der Konferenzserver selbst.
Die gute Nachricht zuerst: Die Endpunkte, die Berechnung von checksum, das XML-Antwortformat und alle Aufzeichnungsendpunkte bleiben unverändert. Bei den meisten Integrationen müssen nur wenige Parameter angepasst werden. Unbekannte oder entfernte Parameter werden ohne Fehlermeldung ignoriert – ein entfernter Parameter verursacht also keinen Fehler, hat aber auch keine Wirkung mehr.
Übersicht aller Änderungen
| Endpunkt | Änderung | Auswirkung | Erforderliche Maßnahme |
|---|---|---|---|
create | lockSettingsDisableNote (Singular) entfernt | Inkompatible Änderung | Verwenden Sie lockSettingsDisableNotes. |
create | Die Standard-Medienbrücke ist jetzt livekit | Verhaltensänderung | Prüfen Sie die Telefoneinwahl mit Gästewarteraum; setzen Sie bei Bedarf audioBridge. |
create | sharedNotesEditor wird ignoriert – Etherpad entfernt | Verhaltensänderung | Entfernen Sie den Parameter; gemeinsame Notizen verwenden immer BlockNote. |
create | meetingEndedURL erhält meetingID und recordingmarks (4.0.1) | Verhaltensänderung | Stellen Sie sicher, dass Ihr Callback-Handler die zusätzlichen Parameter toleriert. |
create | Im Client erstellte Breakout-Räume übernehmen meetingKeepEvents von der übergeordneten Konferenz | Verhaltensänderung | In der Regel keine. |
create | Der Standardwert von meetingLayout ist jetzt UNIFIED_LAYOUT | Verhaltensänderung | In der Regel keine; übergeben Sie meetingLayout explizit, um eines der speziellen Layouts zu verwenden. |
create | Neue Fehlerschlüssel malformedXml und invalidPresentationUrl; die Konferenz wird nicht erstellt | Verhaltensänderung | Prüfen Sie Ihre Fehlerbehandlung für vorab hochgeladene Dokumente. |
create | layouts und captions aus disabledFeatures entfernt | Keine funktionalen Auswirkungen | Entfernen Sie die Werte aus Ihrer Liste. |
create | copyright, logoutTimer, webVoice entfernt | Keine funktionalen Auswirkungen | Entfernen Sie die Parameter (sie hatten bereits zuvor keine Wirkung). |
create, insertDocument | Max. 10 Dokumente pro Aufruf (4.0.1) | Verhaltensänderung | Behandeln Sie documentsDropped oder teilen Sie die Uploads auf. |
create, join | Layouts CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS und VIDEO_FOCUS entfernt | Verhaltensänderung | Verwenden Sie UNIFIED_LAYOUT oder eines der speziellen Layouts. |
create, join | Neue Parameter lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation | Neu | Optional. |
end | Beendet auch über die API erstellte Breakout-Räume | Verhaltensänderung | Entfernen Sie Übergangslösungen, die isBreakout-Räume separat beendet haben. |
insertDocument | Anfragelimit und neue Fehlerschlüssel (4.0.1) | Verhaltensänderung | Behandeln Sie rateLimitExceeded und die neuen messageKey-Werte. |
join | fullName auf 255 Zeichen begrenzt | Inkompatible Änderung | Kürzen Sie Namen; behandeln Sie fullNameTooLong. |
join | webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction und userdata-bbb_parent_room_moderator entfernt | Verhaltensänderung | Ersetzen Sie diese wie unten beschrieben. |
sendChatMessage | Neue Fehlerschlüssel für fehlende Parameter | Verhaltensänderung | Behandeln Sie missingParamMeetingID und missingParamMessage. |
/api/rest/clientSettings | Endpunkt entfernt | Inkompatible Änderung | Rufen Sie ihn nicht mehr auf; verwenden Sie clientSettingsOverride, um die Client-Einstellungen anzupassen. |
Änderungen an create
Entfernte Parameter
| Parameter (3.x) | Status in 4.x | Ersatz |
|---|---|---|
lockSettingsDisableNote | Entfernt (war ein veralteter Alias). Inkompatible Änderung | lockSettingsDisableNotes |
sharedNotesEditor | Wird ignoriert. Etherpad wurde entfernt, jedes Meeting verwendet BlockNote. | Keine. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown und sharedNotesInitialContentMarkdownUrl funktionieren jetzt für jedes Meeting – nicht mehr nur mit sharedNotesEditor=blockNote. |
copyright | Entfernt. Der Wert wurde nie an den Client übergeben. | Client-Einstellung public.app.copyright über clientSettingsOverride (erfordert allowOverrideClientSettingsOnCreateCall=true auf dem Server) oder clientSettingsOverrideJsonUrl. |
logoutTimer | Entfernt. Der Wert wurde nie an den Client übergeben. | — |
webVoice | Entfernt. Seit der Abschaffung des Flash-Clients in BBB 2.3 überflüssig. | voiceBridge |
create?meetingID=demo&name=Demo
&lockSettingsDisableNote=true
&sharedNotesEditor=blockNote
©right=Example+Inc.
&meetingLayout=SMART_LAYOUTcreate?meetingID=demo&name=Demo
&lockSettingsDisableNotes=true
&clientSettingsOverrideJsonUrl=https%3A%2F%2F
example.com%2Fclient-settings.json
&meetingLayout=UNIFIED_LAYOUTLayouts
Die Layout-Auswahl im Client wurde durch ein einziges adaptives Layout ersetzt. UNIFIED_LAYOUT ist der neue Standardwert von meetingLayout, und die klassischen Layouts werden von meetingLayout (bei create), enforceLayout (bei join und getJoinUrl) und userdata-bbb_default_layout nicht mehr akzeptiert:
Entfernte Layout-Werte verursachen keinen Fehler: Der Client ignoriert sie und greift auf die nächste Layout-Quelle zurück (z. B. das Meeting-Layout oder das Standardlayout).
| Wert in 3.x | Status in 4.x | Empfohlener Wert in 4.x |
|---|---|---|
CUSTOM_LAYOUT (Standard in 3.x) | Entfernt | UNIFIED_LAYOUT |
SMART_LAYOUT | Entfernt | UNIFIED_LAYOUT |
PRESENTATION_FOCUS | Entfernt | UNIFIED_LAYOUT; für einen Bildschirm, der nur die Präsentation anzeigt (z. B. einen Projektor), PRESENTATION_ONLY |
VIDEO_FOCUS | Entfernt | UNIFIED_LAYOUT; für eine Kamerawand CAMERAS_ONLY |
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY | Unverändert | — |
CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY und MEDIA_ONLY sind spezielle Layouts für Hybrid- oder Kioskszenarien – sie blenden große Teile der Benutzeroberfläche aus. Verwenden Sie sie in regulären Meetings nicht als 1:1-Ersatz für die entfernten Layouts.
Medienbrücken
audioBridge, cameraBridge und screenShareBridge verwenden jetzt standardmäßig livekit statt bbb-webrtc-sfu. Der Wert freeswitch ist für audioBridge nicht mehr gültig: Der Client behandelt ihn als unbekannte Brücke und greift jetzt auf livekit zurück (zuvor bbb-webrtc-sfu). Verwenden Sie stattdessen audioBridge=bbb-webrtc-sfu.
Personen, die sich telefonisch über die Audiobridge LiveKit einwählen, überspringen den Warteraum für Gäste, selbst mit guestPolicy=ASK_MODERATOR. Wenn Ihre Integration darauf angewiesen ist, dass Moderatoren Telefonteilnehmende zulassen, übergeben Sie audioBridge=bbb-webrtc-sfu bei create. Dadurch wird die Audiobridge auf FreeSWITCH umgestellt.
Hinweis für bbbserver.de-Kunden: Wir arbeiten daran, die Zugangsbeschränkung für Telefonteilnehmende von BigBlueButton auch bei der Verwendung von LiveKit beizubehalten.
Die userdata-Parameter userdata-bbb_listen_only_mode und userdata-bbb_transparent_listen_only werden nur mit audioBridge=bbb-webrtc-sfu ausgewertet. Mit livekit treten Teilnehmer im Nur-Zuhören-Modus immer über eine stummgeschaltete Mikrofonverbindung bei.
disabledFeatures-Werte
| Wert | Änderung |
|---|---|
layouts | Nicht mehr gültig – die Layout-Auswahl wurde aus dem Client entfernt. Keine funktionalen Auswirkungen |
captions | Nicht mehr gültig – hatte seit BBB 3.0 keine Wirkung mehr. Verwenden Sie liveTranscription, um die automatische Transkription zu deaktivieren. Keine funktionalen Auswirkungen |
pinChatMessage | Neu: Deaktiviert das Anheften von Chatnachrichten. Neu |
multiFunctionalMode | Neu: Deaktiviert das zusätzliche Seitenleistenpanel. Neu |
webcamGrid | Neu: Deaktiviert die Avatar-Kacheln für Benutzer ohne Kamera, während die Präsentation minimiert ist. Neu |
Vorab hochgeladene Präsentationen
Seit BBB 4.0.1 lädt ein create-Aufruf höchstens 10 Dokumente hoch (Servereinstellung maxPresentationsPerRequest; die Standardpräsentation wird nicht mitgezählt). Das mit current="true" markierte Dokument wird immer beibehalten, die anderen folgen in der Reihenfolge der Anfrage. Überzählige Dokumente werden verworfen, das Meeting wird jedoch trotzdem erstellt und die Antwort enthält messageKey=documentsDropped:
<response>
<returncode>SUCCESS</returncode>
<meetingID>demo</meetingID>
<!-- ... -->
<messageKey>documentsDropped</messageKey>
<message>...</message>
</response> Beachten Sie, dass messageKey jetzt documentsDropped bei SUCCESS sein kann. Wenn Ihr Code jedes messageKey als Fehler behandelt oder nur auf duplicateWarning prüft, passen Sie ihn an. Laden Sie anschließend weitere Dokumente mit insertDocument hoch.
Außerdem prüft create jetzt den Anfrageinhalt, bevor das Meeting erstellt wird: Bei nicht wohlgeformtem XML schlägt die Anfrage mit messageKey=malformedXml fehl, bei einer Dokument-URL mit ungültiger Syntax mit messageKey=invalidPresentationUrl. In beiden Fällen wird das Meeting nicht erstellt.
Callback bei Meeting-Ende
Seit BBB 4.0.1 hängt der Callback meetingEndedURL die Parameter meetingID und recordingmarks an den Query-String Ihrer URL an (4.0.0 rief die URL unverändert auf). Vorhandene Parameter behalten ihre Werte, können aber neu kodiert werden. Wenn Ihre URL bereits einen Parameter mit demselben Namen enthält, werden beide Werte gesendet – Ihrer zuerst.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoFalls Sie noch meta_endCallbackUrl verwenden: Die offizielle Dokumentation empfiehlt jetzt stattdessen meetingEndedURL, da Werte von meta_* für Benutzer im Meeting sichtbar sein können und dadurch geheime Tokens in der Callback-URL offengelegt werden könnten. Prüfen Sie keine Signatur anhand des unverarbeiteten Query-Strings, da dieser neu kodiert werden kann.
Weitere Änderungen
- Im Client erstellte Breakout-Räume übernehmen jetzt den tatsächlich wirksamen Wert von
meetingKeepEventsihres übergeordneten Meetings (zuvor verwendeten sie immer den Server-StandardwertdefaultKeepEvents). Breakout-Räume, die Sie selbst übercreatemitisBreakout=trueerstellen, verwenden weiterhin ihren eigenen ParametermeetingKeepEvents.
Neue Parameter
| Parameter | Standard | Beschreibung |
|---|---|---|
lockSettingsPresenterPolicy | requireApproval | Richtlinie „Präsentationsrecht anfordern“: moderatorOnly, requireApproval oder freeForAll. |
requireUserConsentBeforeUnmuting | false | Mit true müssen Benutzer zustimmen, bevor ein Moderator ihre Stummschaltung aufhebt (nur bei allowModsToUnmuteUsers=true relevant). |
Der Standardwert requireApproval bedeutet, dass Zuschauer jetzt im Client die Präsentatorrolle anfordern können. Wenn nur Moderatoren die Präsentatorrolle zuweisen sollen, übergeben Sie lockSettingsPresenterPolicy=moderatorOnly.
Alle Details: Meeting erstellen (4.x).
Änderungen an join
| Parameter | Änderung | Erforderliche Maßnahmen |
|---|---|---|
fullName | Auf 255 Zeichen begrenzt. Längere Werte werden mit fullNameTooLong abgelehnt (zuvor unbegrenzt). | Kürzen Sie Anzeigenamen, bevor Sie die Beitritts-URL erstellen. |
enforceLayout | Nur UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY und MEDIA_ONLY werden akzeptiert. | Ordnen Sie alte Werte wie in der obigen Layout-Tabelle angegeben zu. |
webVoiceConf | Entfernt (der Wert wurde nie ausgelesen). | Entfernen Sie den Parameter. |
userdata-bbb_change_layout | Entfernt; die zugehörigen Werte smart, videoFocus, presentationFocus und custom existieren nicht mehr. | Verwenden Sie userdata-bbb_default_layout. |
userdata-enable-user-reaction | Entfernt. | Verwenden Sie disabledFeatures=userReactions bei create oder die Client-Einstellung public.userReaction.enabled. |
userdata-bbb_parent_room_moderator | In 4.0.1 entfernt; seit 3.0.25 hatte dies keine Wirkung mehr. | Weisen Sie die Rolle im Breakout-Raum mit role zu. |
userdata-bbb_hide_sidebar_navigation | Neu: Schließt beim Beitritt die Seitenleistennavigation und den Seitenleistenbereich. Neu | Optional. |
join?meetingID=demo&role=VIEWER
&fullName=<any length>
&enforceLayout=PRESENTATION_FOCUS
&userdata-bbb_change_layout=smartjoin?meetingID=demo&role=VIEWER
&fullName=<max. 255 characters>
&enforceLayout=UNIFIED_LAYOUT
&userdata-bbb_default_layout=UNIFIED_LAYOUTÄnderungen an insertDocument
- Höchstens 10 Dokumente pro Aufruf (
maxPresentationsPerRequest). Überzählige Dokumente werden verworfen, die Antwort lautet weiterhinSUCCESSmitmessageKey=documentsDropped. - Aufruflimit pro Meeting: standardmäßig 30 Aufrufe pro 60 Sekunden. Aufrufe oberhalb des Limits schlagen mit
rateLimitExceededfehl – versuchen Sie es nach einer Wartezeit erneut. - Jede Antwort vom Typ
FAILEDenthält jetzt einen Wert fürmessageKey:notFound,malformedXml,invalidPresentationUrl,invalidFilename,presentationDisabled,noDocuments.
Wenn Ihre Fehlerbehandlung den Text von message vergleicht, stellen Sie auf messageKey um. Details: Präsentation einfügen (4.x).
Änderungen an end
Das Beenden eines Meetings beendet jetzt auch alle zugehörigen Breakout-Räume, einschließlich der Räume, die über create mit isBreakout=true erstellt wurden. Zuvor endeten nur im Client erstellte Breakout-Räume zusammen mit ihrem übergeordneten Meeting. Wenn Ihre Anwendung solche Räume mit separaten end-Aufrufen beendet hat, sind diese Aufrufe nicht mehr erforderlich – stellen Sie sicher, dass Ihr Code mit einem bereits beendeten Breakout-Raum umgehen kann.
Änderungen an sendChatMessage
Der Wert von messageKey bei fehlenden Parametern hat sich geändert: Fehlt message, wird jetzt missingParamMessage zurückgegeben (zuvor nullError); fehlt meetingID, wird missingParamMeetingID zurückgegeben (zuvor meetingNotFound). Bei Längenüberschreitungen wird weiterhin sizeError zurückgegeben, bei ungültigen Zeichen in meetingID weiterhin validationError.
Entfernte Endpunkte und Änderungen auf HTTP-Ebene
/api/rest/clientSettingswurde entfernt. Client-Einstellungen werden jetzt über GraphQL innerhalb des Clients bereitgestellt; passen Sie sie pro Meeting mitclientSettingsOverrideoderclientSettingsOverrideJsonUrlan.- Die Etherpad-bezogenen Teile der GraphQL-API wurden entfernt. Plugins oder Integrationen, die diese abfragen, erhalten einen Validierungsfehler.
- Unbekannte URLs unterhalb von
/bigbluebutton/geben404mit einem Antwortinhalt vom Typ JSON statt eines Dokuments vom Typ XML zurück. - Anfragen mit mehr als 10,000 Parametern werden mit
HTTP 500beantwortet. - CORS-Preflight-Anfragen ohne CORS-Konfiguration geben
200ohneAccess-Control-*-Header zurück (zuvor403);Vary: Originwird nicht mehr gesendet. - Alle Antworten enthalten die Sicherheitsheader
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyundX-XSS-Protection. Wenn Sie API-Antworten in Frames einbetten, prüfen SieX-Frame-Options.
Die Änderungen an 404-Antworten, das Parameterlimit und die Änderungen an CORS-Preflight-Anfragen gelten bereits seit BBB 3.0.40 (bbb-web auf Grails 8); sie betreffen Sie nur, wenn Ihre Server eine ältere 3.0-Version ausführen. Die Sicherheitsheader sind neu in 4.0 – unter BBB 3.0.40 sind sie deaktiviert.
Unverändert
Die folgenden Teile der API sind in 3.x und 4.x identisch – es sind keine Änderungen erforderlich:
- Berechnung von Checksum und unterstützte Hash-Algorithmen (SHA-1, SHA-256, SHA-384, SHA-512)
isMeetingRunning,getMeetings,getMeetingInfo(Parameter und Antwortformat)getRecordings,publishRecordings,deleteRecordings,updateRecordings,getRecordingTextTracks,putRecordingTextTrack- Webhooks, mit Ausnahme des Ereignisses
pad-content, das aufgrund der Entfernung von Etherpad nicht mehr existiert - Rollenzuweisung über
rolebeijoin(eingeführt in BBB 2.4)
Server-Einstellungen, die das API-Verhalten beeinflussen
Diese Einstellungen werden vom Serverbetreiber in bbb-web.properties konfiguriert, nicht über API-Parameter. Wenn Sie eigene Server betreiben oder Ihr Anbieter diese Einstellungen ändert, kann sich das Verhalten Ihrer API-Aufrufe ändern:
| Einstellung | Änderung in 4.x |
|---|---|
allowDuplicateExtUserid | Entfernt. Mehrfache Beitritte mit demselben Wert für userID werden jetzt durch maxUserConcurrentAccesses gesteuert. |
defaultMeetingLayout | Standardwert UNIFIED_LAYOUT (zuvor CUSTOM_LAYOUT). |
audioBridge, cameraBridge, screenShareBridge | Standardwert: livekit. |
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec | Neue Grenzwerte (Standardwerte: 10, 30, 60). |
accessControlAllowOrigin | Entfernt; CORS wird über grails.cors.* konfiguriert. |
Checkliste für die Migration
Durchsuchen Sie Ihren Code nach entfernten Werten: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction und clientSettings.
Bereinigen Sie disabledFeatures: Entfernen Sie layouts und captions.
Begrenzen Sie Anzeigenamen auf 255 Zeichen und behandeln Sie fullNameTooLong.
Überprüfen Sie Präsentationsuploads: maximal 10 Dokumente pro create/insertDocument-Aufruf; behandeln Sie documentsDropped und rateLimitExceeded.
Überprüfen Sie Ihren Callback-Handler für meetingEndedURL: Er muss die zusätzlichen Parameter meetingID und recordingmarks akzeptieren.
Entscheiden Sie über neue Standardeinstellungen: Präsentatoranfragen (lockSettingsPresenterPolicy) und den Gästewarteraum für Telefonteilnehmer (audioBridge).
Testen Sie mit einem 4.x-Server – insbesondere Breakout-Räume, Präsentationsuploads und Ihre auf messageKey basierende Fehlerbehandlung.
Ihre Integration muss eine Zeit lang beide Versionen unterstützen? Alle oben genannten Änderungen sind in einer Richtung abwärtskompatibel: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout und Anzeigenamen mit höchstens 255 Zeichen funktionieren auch auf BBB 3.0.19+-Servern. Verwenden Sie diese überall, damit Ihre API-Aufrufe mit beiden Versionen funktionieren.
Suchen Sie die bisherige Dokumentation? Die vollständige 3.x-Referenz bleibt verfügbar, z. B. Meeting erstellen (3.x).
Häufig gestellte Fragen
UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) werden bereits von BBB 3.0.19 unterstützt. Bereiten Sie Ihren Code so vor, dass das Server-Upgrade keine gleichzeitige Veröffentlichung einer neuen Version Ihrer Anwendung erfordert.sha(apiCallName + queryString + sharedSecret) mit denselben unterstützten Hash-Algorithmen berechnet.