API-versie: 4.x nieuwste 3.x
Hoofdstuk 2

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

Lay-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.

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

Als 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 meetingKeepEvents over van hun bovenliggende vergadering (voorheen gebruikten ze altijd de serverstandaard defaultKeepEvents). Breakoutruimtes die je zelf via create met isBreakout=true aanmaakt, gebruiken nog steeds hun eigen meetingKeepEvents-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.
Voor (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Na (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Wijzigingen in insertDocument

  • Maximaal 10 documenten per aanroep (maxPresentationsPerRequest). Overtollige documenten worden genegeerd; het antwoord is nog steeds SUCCESS met messageKey=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 een messageKey: 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/clientSettings is verwijderd. Clientinstellingen worden nu via GraphQL binnen de client geleverd; pas ze per vergadering aan met clientSettingsOverride of clientSettingsOverrideJsonUrl.
  • 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/ retourneren 404 met 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 200 zonder Access-Control-*-headers (voorheen 403); Vary: Origin wordt niet meer verzonden.
  • Alle antwoorden bevatten de beveiligingsheaders X-Frame-Options, X-Content-Type-Options, Referrer-Policy en X-XSS-Protection. Als je API-antwoorden in frames insluit, controleer dan X-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 role op join (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

Je kunt – en zou moeten – dit vooraf doen. De aanbevolen vervangingen (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.

Nee. BigBlueButton negeert onbekende parameters, dus een verwijderde parameter heeft zonder melding geen effect. Daarom zijn verwijderde parameters gemakkelijk over het hoofd te zien – controleer je code aan de hand van de lijsten in deze handleiding.

Nee. De checksum wordt nog steeds berekend als sha(apiCallName + queryString + sharedSecret) met dezelfde ondersteunde hash-algoritmen.

Nee. Deze handleiding behandelt alleen wijzigingen in de API-aanroepen die je applicatie doet. Het upgraden van de conferentieservers zelf is een apart onderwerp en wordt door je serverbeheerder uitgevoerd.