API-Version: 4.x neueste 3.x
Kapitel 2

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
Vorher (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
Nachher (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Layouts

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.

Callback (3.x)
GET https://example.com/ended?token=a817dde5
Callback (4.0.1+)
GET https://example.com/ended?token=a817dde5
  &recordingmarks=true&meetingID=demo

Falls 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 meetingKeepEvents ihres übergeordneten Meetings (zuvor verwendeten sie immer den Server-Standardwert defaultKeepEvents). Breakout-Räume, die Sie selbst über create mit isBreakout=true erstellen, verwenden weiterhin ihren eigenen Parameter meetingKeepEvents.

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.
Vorher (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Nachher (4.x)
join?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 weiterhin SUCCESS mit messageKey=documentsDropped.
  • Aufruflimit pro Meeting: standardmäßig 30 Aufrufe pro 60 Sekunden. Aufrufe oberhalb des Limits schlagen mit rateLimitExceeded fehl – versuchen Sie es nach einer Wartezeit erneut.
  • Jede Antwort vom Typ FAILED enthält jetzt einen Wert für messageKey: 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/clientSettings wurde entfernt. Client-Einstellungen werden jetzt über GraphQL innerhalb des Clients bereitgestellt; passen Sie sie pro Meeting mit clientSettingsOverride oder clientSettingsOverrideJsonUrl an.
  • Die Etherpad-bezogenen Teile der GraphQL-API wurden entfernt. Plugins oder Integrationen, die diese abfragen, erhalten einen Validierungsfehler.
  • Unbekannte URLs unterhalb von /bigbluebutton/ geben 404 mit einem Antwortinhalt vom Typ JSON statt eines Dokuments vom Typ XML zurück.
  • Anfragen mit mehr als 10,000 Parametern werden mit HTTP 500 beantwortet.
  • CORS-Preflight-Anfragen ohne CORS-Konfiguration geben 200 ohne Access-Control-*-Header zurück (zuvor 403); Vary: Origin wird nicht mehr gesendet.
  • Alle Antworten enthalten die Sicherheitsheader X-Frame-Options, X-Content-Type-Options, Referrer-Policy und X-XSS-Protection. Wenn Sie API-Antworten in Frames einbetten, prüfen Sie X-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 role bei join (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

Sie können – und sollten – dies im Voraus tun. Die empfohlenen Alternativen (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.

Nein. BigBlueButton ignoriert unbekannte Parameter, sodass ein entfernter Parameter ohne Fehlermeldung wirkungslos bleibt. Deshalb werden entfernte Parameter leicht übersehen – gleichen Sie Ihren Code mit den Listen in diesem Leitfaden ab.

Nein. Die checksum wird weiterhin als sha(apiCallName + queryString + sharedSecret) mit denselben unterstützten Hash-Algorithmen berechnet.

Nein. Dieser Leitfaden behandelt ausschließlich Änderungen an den API-Aufrufen Ihrer Anwendung. Das Upgrade der Konferenzserver selbst ist ein separates Thema und wird von Ihrem Serverbetreiber durchgeführt.