Migreren van 3.x naar 4.x
BigBlueButton 4.0 verwijdert een aantal verouderde parameters en lay-outwaarden, wijzigt verschillende standaardwaarden en introduceert nieuwe foutsleutels. Deze handleiding vermeldt alles wat je in je API-aanroepen moet controleren wanneer je integratie met een BigBlueButton 4.x-server communiceert in plaats van met een BigBlueButton 3.x-server.
Reikwijdte: Deze handleiding behandelt de wijzigingen in API-aanroepen die je applicatie uitvoert (create, join, insertDocument, …). Het upgraden of migreren van de conferentieservers zelf wordt niet behandeld.
Eerst het goede nieuws: de endpoints, de berekening van checksum, het XML-responsformaat en alle opname-endpoints blijven ongewijzigd. De meeste integraties hoeven slechts enkele parameters aan te passen. Onbekende of verwijderde parameters worden zonder melding genegeerd – een verwijderde parameter veroorzaakt dus geen fout, maar heeft ook geen effect meer.
Overzicht van alle wijzigingen
| Endpoint | Wijziging | Impact | Vereiste actie |
|---|---|---|---|
create | lockSettingsDisableNote (enkelvoud) verwijderd | Niet achterwaarts compatibel | Gebruik lockSettingsDisableNotes. |
create | De standaardmediabridge is nu livekit | Gedragswijziging | Controleer telefonisch inbellen met de wachtkamer voor gasten; stel indien nodig audioBridge in. |
create | sharedNotesEditor genegeerd – Etherpad verwijderd | Gedragswijziging | Verwijder de parameter; gedeelde notities gebruiken altijd BlockNote. |
create | meetingEndedURL ontvangt meetingID en recordingmarks (4.0.1) | Gedragswijziging | Zorg ervoor dat je callbackhandler de extra parameters accepteert. |
create | Breakoutrooms die in de client worden aangemaakt, erven meetingKeepEvents van de hoofdvergadering | Gedragswijziging | Meestal geen. |
create | De standaardwaarde van meetingLayout is nu UNIFIED_LAYOUT | Gedragswijziging | Meestal geen; geef meetingLayout expliciet mee om een van de speciale lay-outs te gebruiken. |
create | Nieuwe foutsleutels malformedXml en invalidPresentationUrl; de vergadering wordt niet aangemaakt | Gedragswijziging | Controleer je foutafhandeling voor vooraf geüploade documenten. |
create | layouts en captions verwijderd uit disabledFeatures | Geen functionele impact | Verwijder de waarden uit je lijst. |
create | copyright, logoutTimer, webVoice verwijderd | Geen functionele impact | Verwijder de parameters (ze hadden voorheen al geen effect). |
create, insertDocument | Max. 10 documenten per aanroep (4.0.1) | Gedragswijziging | Handel documentsDropped af of splits uploads op. |
create, join | Lay-outs CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS en VIDEO_FOCUS verwijderd | Gedragswijziging | Gebruik UNIFIED_LAYOUT of een van de speciale lay-outs. |
create, join | Nieuwe parameters lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation | Nieuw | Optioneel. |
end | Beëindigt ook breakout-ruimtes die via de API zijn aangemaakt | Gedragswijziging | Verwijder tijdelijke oplossingen die isBreakout-ruimtes afzonderlijk beëindigden. |
insertDocument | Verzoeklimiet en nieuwe foutsleutels (4.0.1) | Gedragswijziging | Verwerk rateLimitExceeded en de nieuwe waarden voor messageKey. |
join | fullName beperkt tot 255 tekens | Niet achterwaarts compatibel | Kort namen in; verwerk fullNameTooLong. |
join | webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction en userdata-bbb_parent_room_moderator verwijderd | Gedragswijziging | Vervang zoals hieronder beschreven. |
sendChatMessage | Nieuwe foutsleutels voor ontbrekende parameters | Gedragswijziging | Verwerk missingParamMeetingID en missingParamMessage. |
/api/rest/clientSettings | Endpoint verwijderd | Niet achterwaarts compatibel | Roep dit niet meer aan; gebruik clientSettingsOverride om clientinstellingen aan te passen. |
Wijzigingen in create
Verwijderde parameters
| Parameter (3.x) | Status in 4.x | Vervanging |
|---|---|---|
lockSettingsDisableNote | Verwijderd (was een verouderde alias). Niet achterwaarts compatibel | lockSettingsDisableNotes |
sharedNotesEditor | Genegeerd. Etherpad is verwijderd; elke vergadering gebruikt BlockNote. | Geen. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown en sharedNotesInitialContentMarkdownUrl werken nu voor elke vergadering – niet langer alleen met sharedNotesEditor=blockNote. |
copyright | Verwijderd. De waarde werd nooit aan de client doorgegeven. | Clientinstelling public.app.copyright via clientSettingsOverride (vereist allowOverrideClientSettingsOnCreateCall=true op de server) of clientSettingsOverrideJsonUrl. |
logoutTimer | Verwijderd. De waarde werd nooit aan de client doorgegeven. | — |
webVoice | Verwijderd. Overbodig sinds de Flash-client in BBB 2.3 is afgeschaft. | 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_LAYOUTLay-outs
De lay-outkeuze in de client is vervangen door één adaptieve lay-out. UNIFIED_LAYOUT is de nieuwe standaardwaarde van meetingLayout, en de klassieke lay-outs worden niet langer geaccepteerd door meetingLayout (bij create), enforceLayout (bij join en getJoinUrl) en userdata-bbb_default_layout:
Verwijderde lay-outwaarden veroorzaken geen fout: de client negeert ze en valt terug op de volgende lay-outbron (bijvoorbeeld de vergaderlay-out of de standaardlay-out).
| Waarde in 3.x | Status in 4.x | Aanbevolen waarde in 4.x |
|---|---|---|
CUSTOM_LAYOUT (standaard in 3.x) | Verwijderd | UNIFIED_LAYOUT |
SMART_LAYOUT | Verwijderd | UNIFIED_LAYOUT |
PRESENTATION_FOCUS | Verwijderd | UNIFIED_LAYOUT; voor een scherm dat alleen de presentatie toont (bijvoorbeeld een projector) PRESENTATION_ONLY |
VIDEO_FOCUS | Verwijderd | UNIFIED_LAYOUT; voor een camerawand CAMERAS_ONLY |
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY | Ongewijzigd | — |
CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY en MEDIA_ONLY zijn speciale lay-outs voor hybride vergaderingen of kiosktoepassingen – ze verbergen grote delen van de gebruikersinterface. Gebruik ze niet als een-op-eenvervanging voor de verwijderde lay-outs in reguliere vergaderingen.
Mediabridges
audioBridge, cameraBridge en screenShareBridge hebben nu standaard de waarde livekit in plaats van bbb-webrtc-sfu. De waarde freeswitch is niet langer geldig voor audioBridge: de client behandelt deze als een onbekende bridge en valt nu terug op livekit (voorheen bbb-webrtc-sfu). Gebruik in plaats daarvan audioBridge=bbb-webrtc-sfu.
Deelnemers die telefonisch inbellen op de LiveKit-audiobridge slaan de wachtkamer voor gasten over, zelfs met guestPolicy=ASK_MODERATOR. Als je integratie afhankelijk is van moderators die telefonische deelnemers toelaten, geef dan audioBridge=bbb-webrtc-sfu mee bij create, waarmee de audiobridge wordt omgeschakeld naar FreeSWITCH.
Opmerking voor bbbserver.de-klanten: we werken eraan om de beperking op telefonische toegang van BigBlueButton ook bij gebruik van LiveKit te behouden.
De parameters van userdata, userdata-bbb_listen_only_mode en userdata-bbb_transparent_listen_only, worden alleen geëvalueerd bij gebruik van audioBridge=bbb-webrtc-sfu. Bij gebruik van livekit nemen gebruikers in de alleen-luisterenmodus altijd deel via een gedempte microfoonverbinding.
Waarden voor disabledFeatures
| Waarde | Wijziging |
|---|---|
layouts | Niet langer geldig – de lay-outkeuze is uit de client verwijderd. Geen functionele impact |
captions | Niet langer geldig – had sinds BBB 3.0 geen effect meer. Gebruik liveTranscription om automatische transcriptie uit te schakelen. Geen functionele impact |
pinChatMessage | Nieuw: schakelt het vastzetten van chatberichten uit. Nieuw |
multiFunctionalMode | Nieuw: schakelt het extra zijbalkpaneel uit. Nieuw |
webcamGrid | Nieuw: schakelt de avatartegels voor gebruikers zonder camera uit terwijl de presentatie is geminimaliseerd. Nieuw |
Vooraf geüploade presentaties
Sinds BBB 4.0.1 uploadt een create-aanroep maximaal 10 documenten (serverinstelling maxPresentationsPerRequest; de standaardpresentatie telt niet mee). Het document dat als current="true" is gemarkeerd, blijft altijd behouden; de overige volgen in de volgorde van het verzoek. Overtollige documenten worden weggelaten, maar de vergadering wordt wel aangemaakt en het antwoord bevat messageKey=documentsDropped:
<response>
<returncode>SUCCESS</returncode>
<meetingID>demo</meetingID>
<!-- ... -->
<messageKey>documentsDropped</messageKey>
<message>...</message>
</response> Let op: messageKey kan nu documentsDropped zijn op SUCCESS. Als je code elke messageKey als een fout behandelt of alleen op duplicateWarning controleert, pas deze dan aan. Upload daarna aanvullende documenten met insertDocument.
Daarnaast controleert create nu de inhoud van het verzoek voordat de vergadering wordt aangemaakt: als de inhoud geen correct gevormde XML is, mislukt het verzoek met messageKey=malformedXml; bij een document-URL met ongeldige syntaxis mislukt het verzoek met messageKey=invalidPresentationUrl. In beide gevallen wordt de vergadering niet aangemaakt.
Callback bij beëindiging van een vergadering
Sinds BBB 4.0.1 voegt de meetingEndedURL-callback meetingID en recordingmarks toe aan de querystring van je URL (4.0.0 riep de URL ongewijzigd aan). Bestaande parameters behouden hun waarden, maar kunnen opnieuw worden gecodeerd. Als je URL al een parameter met dezelfde naam bevat, worden beide waarden verzonden – die van jou eerst.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoAls je nog meta_endCallbackUrl gebruikt: de officiële documentatie beveelt nu meetingEndedURL aan als alternatief, omdat waarden van meta_* zichtbaar kunnen zijn voor gebruikers in de vergadering en geheime tokens in de callback-URL kunnen lekken. Verifieer geen handtekening op basis van de onbewerkte querystring, aangezien deze opnieuw kan worden gecodeerd.
Overige wijzigingen
- Breakoutruimtes die in de client worden aangemaakt, nemen nu de effectieve waarde van
meetingKeepEventsover van hun bovenliggende vergadering (voorheen gebruikten ze altijd de serverstandaarddefaultKeepEvents). Breakoutruimtes die je zelf viacreatemetisBreakout=trueaanmaakt, gebruiken nog steeds hun eigenmeetingKeepEvents-parameter.
Nieuwe parameters
| Parameter | Standaard | Beschrijving |
|---|---|---|
lockSettingsPresenterPolicy | requireApproval | Beleid voor 'Verzoek om te presenteren': moderatorOnly, requireApproval of freeForAll. |
requireUserConsentBeforeUnmuting | false | Met true moeten gebruikers toestemming geven voordat een moderator hun microfoon inschakelt (alleen relevant bij allowModsToUnmuteUsers=true). |
De standaardwaarde requireApproval betekent dat kijkers nu de presentatorrol kunnen aanvragen in de client. Als alleen moderators de presentatorrol mogen toewijzen, geef dan lockSettingsPresenterPolicy=moderatorOnly mee.
Alle details: Vergadering maken (4.x).
Wijzigingen in join
| Parameter | Wijziging | Wat je moet doen |
|---|---|---|
fullName | Beperkt tot 255 tekens. Langere waarden worden geweigerd met fullNameTooLong (voorheen onbeperkt). | Kort weergavenamen in voordat je de deelname-URL samenstelt. |
enforceLayout | Alleen UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY en MEDIA_ONLY worden geaccepteerd. | Zet oude waarden om zoals aangegeven in de bovenstaande lay-outtabel. |
webVoiceConf | Verwijderd (de waarde werd nooit uitgelezen). | Verwijder de parameter. |
userdata-bbb_change_layout | Verwijderd; de bijbehorende waarden smart, videoFocus, presentationFocus en custom bestaan niet meer. | Gebruik userdata-bbb_default_layout. |
userdata-enable-user-reaction | Verwijderd. | Gebruik disabledFeatures=userReactions op create of de clientinstelling public.userReaction.enabled. |
userdata-bbb_parent_room_moderator | Verwijderd in 4.0.1; had sinds 3.0.25 geen effect meer. | Wijs de rol in de breakoutruimte toe met role. |
userdata-bbb_hide_sidebar_navigation | Nieuw: sluit de zijbalknavigatie en het zijbalkpaneel bij deelname. Nieuw | Optioneel. |
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_LAYOUTWijzigingen in insertDocument
- Maximaal 10 documenten per aanroep (
maxPresentationsPerRequest). Overtollige documenten worden genegeerd; het antwoord is nog steedsSUCCESSmetmessageKey=documentsDropped. - Aanroeplimiet per vergadering: standaard 30 aanroepen per 60 seconden. Aanroepen boven de limiet mislukken met
rateLimitExceeded– probeer het na enige tijd opnieuw. - Elk
FAILED-antwoord bevat nu eenmessageKey:notFound,malformedXml,invalidPresentationUrl,invalidFilename,presentationDisabled,noDocuments.
Als je foutafhandeling de tekst van message vergelijkt, stap dan over op messageKey. Details: Presentatie invoegen (4.x).
Wijzigingen in end
Het beëindigen van een vergadering beëindigt nu ook alle bijbehorende breakoutruimtes, inclusief ruimtes die via create met isBreakout=true zijn aangemaakt. Voorheen werden alleen breakoutruimtes die vanuit de client waren aangemaakt samen met hun bovenliggende vergadering beëindigd. Als je applicatie zulke ruimtes met afzonderlijke end-aanroepen beëindigde, zijn deze aanroepen niet meer nodig – zorg ervoor dat je code kan omgaan met een breakoutruimte die al is beëindigd.
Wijzigingen in sendChatMessage
De messageKey voor ontbrekende parameters is gewijzigd: een ontbrekende message retourneert nu missingParamMessage (voorheen nullError), een ontbrekende meetingID retourneert missingParamMeetingID (voorheen meetingNotFound). Overschrijdingen van de toegestane lengte retourneren nog steeds sizeError, ongeldige tekens in meetingID retourneren nog steeds validationError.
Verwijderde eindpunten en wijzigingen op HTTP-niveau
/api/rest/clientSettingsis verwijderd. Clientinstellingen worden nu via GraphQL binnen de client geleverd; pas ze per vergadering aan metclientSettingsOverrideofclientSettingsOverrideJsonUrl.- De Etherpad-gerelateerde onderdelen van de GraphQL-API zijn verwijderd. Plug-ins of integraties die deze opvragen, ontvangen een validatiefout.
- Onbekende URL's onder
/bigbluebutton/retourneren404met een JSON-antwoordinhoud in plaats van een XML-document. - Verzoeken met meer dan 10,000 parameters worden beantwoord met
HTTP 500. - CORS-preflightverzoeken zonder CORS-configuratie retourneren
200zonderAccess-Control-*-headers (voorheen403);Vary: Originwordt niet meer verzonden. - Alle antwoorden bevatten de beveiligingsheaders
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyenX-XSS-Protection. Als je API-antwoorden in frames insluit, controleer danX-Frame-Options.
De wijzigingen in 404-antwoorden, de parameterlimiet en CORS-preflightverzoeken gelden al sinds BBB 3.0.40 (bbb-web op Grails 8); ze hebben alleen gevolgen voor je als je servers een oudere 3.0-release draaien. De beveiligingsheaders zijn nieuw in 4.0 – op BBB 3.0.40 zijn ze uitgeschakeld.
Ongewijzigd
De volgende onderdelen van de API zijn identiek in 3.x en 4.x – er zijn geen wijzigingen nodig:
- Berekening van Checksum en ondersteunde hashalgoritmen (SHA-1, SHA-256, SHA-384, SHA-512)
isMeetingRunning,getMeetings,getMeetingInfo(Parameters en antwoordformaat)getRecordings,publishRecordings,deleteRecordings,updateRecordings,getRecordingTextTracks,putRecordingTextTrack- Webhooks, behalve de
pad-content-gebeurtenis, die niet meer bestaat omdat Etherpad is verwijderd - Roltoewijzing via
roleopjoin(geïntroduceerd in BBB 2.4)
Serverinstellingen die het gedrag van de API beïnvloeden
Deze instellingen worden door de serverbeheerder geconfigureerd in bbb-web.properties, niet via API-parameters. Als je je eigen servers beheert of je provider deze instellingen wijzigt, kan het gedrag van je API-aanroepen veranderen:
| Instelling | Wijziging in 4.x |
|---|---|
allowDuplicateExtUserid | Verwijderd. Meerdere deelnames met dezelfde userID worden nu geregeld door maxUserConcurrentAccesses. |
defaultMeetingLayout | Standaard UNIFIED_LAYOUT (voorheen CUSTOM_LAYOUT). |
audioBridge, cameraBridge, screenShareBridge | Standaard livekit. |
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec | Nieuwe limieten (standaardwaarden 10, 30, 60). |
accessControlAllowOrigin | Verwijderd; CORS wordt geconfigureerd via grails.cors.*. |
Migratiechecklist
Doorzoek je code op verwijderde waarden: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction en clientSettings.
Schoon disabledFeatures op: verwijder layouts en captions.
Beperk weergavenamen tot 255 tekens en handel fullNameTooLong af.
Controleer presentatie-uploads: niet meer dan 10 documenten per create/insertDocument-aanroep, handel documentsDropped en rateLimitExceeded af.
Controleer je callback-handler voor meetingEndedURL: deze moet de aanvullende parameters meetingID en recordingmarks accepteren.
Bepaal de nieuwe standaardwaarden: presentatorverzoeken (lockSettingsPresenterPolicy) en de gastenlobby voor telefonische deelnemers (audioBridge).
Test met een 4.x-server – met name breakout-ruimtes, presentatie-uploads en je foutafhandeling op basis van messageKey.
Moet je integratie een tijdje beide versies ondersteunen? Alle bovenstaande wijzigingen zijn in één richting achterwaarts compatibel: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout en weergavenamen van maximaal 255 tekens werken ook op BBB 3.0.19+-servers. Gebruik ze overal, dan werken je API-aanroepen op beide versies.
Zoek je de vorige documentatie? De volledige 3.x-referentie blijft beschikbaar, bijvoorbeeld Vergadering maken (3.x).
Veelgestelde vragen
UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) worden al ondersteund door BBB 3.0.19. Bereid je code zo voor dat de serverupgrade geen gelijktijdige release van je applicatie vereist.sha(apiCallName + queryString + sharedSecret) met dezelfde ondersteunde hash-algoritmen.