API-version: 4.x seneste 3.x
Kapitel 2

Migrer fra 3.x til 4.x

BigBlueButton 4.0 fjerner en række forældede parametre og layoutværdier, ændrer flere standardværdier og introducerer nye fejlnøgler. Denne vejledning viser alt, hvad du skal kontrollere i dine API-kald, når din integration kommunikerer med en BigBlueButton 4.x-server i stedet for en BigBlueButton 3.x-server.

Omfang: Denne vejledning dækker ændringerne i API-kald, som din applikation foretager (create, join, insertDocument, …). Den dækker ikke opgradering eller migrering af selve konferenceserverne.

Den gode nyhed først: Endpoints, beregningen af checksum, svarformatet XML og alle endpoints til optagelser er uændrede. De fleste integrationer behøver kun at justere nogle få parametre. Ukendte eller fjernede parametre ignoreres uden fejlmeddelelse – en fjernet parameter udløser altså ikke en fejl, men har heller ikke længere nogen effekt.

Oversigt over alle ændringer

Endepunkt Ændring Påvirkning Påkrævet handling
create lockSettingsDisableNote (ental) fjernet Bagudinkompatibel ændring Brug lockSettingsDisableNotes.
create Standardmediebroen er nu livekit Ændret adfærd Kontrollér telefonopkald med gæsteventeværelse; angiv audioBridge om nødvendigt.
create sharedNotesEditor ignoreres – Etherpad fjernet Ændret adfærd Fjern parameteren; fælles noter bruger altid BlockNote.
create meetingEndedURL modtager meetingID og recordingmarks (4.0.1) Ændret adfærd Sørg for, at din callback-håndtering kan håndtere de ekstra parametre.
create Grupperum, der oprettes i klienten, arver meetingKeepEvents fra hovedmødet Ændret adfærd Normalt ingen.
create Standardværdien for meetingLayout er nu UNIFIED_LAYOUT Ændret adfærd Normalt ingen; angiv meetingLayout eksplicit for at bruge et af de særlige layouts.
create Nye fejlnøgler malformedXml og invalidPresentationUrl; mødet oprettes ikke Ændret adfærd Kontrollér din fejlhåndtering for forhåndsuploadede dokumenter.
create layouts og captions fjernet fra disabledFeatures Ingen funktionel påvirkning Fjern værdierne fra din liste.
create copyright, logoutTimer, webVoice fjernet Ingen funktionel påvirkning Fjern parametrene (de havde heller ingen effekt før).
create, insertDocument Maks. 10 dokumenter pr. kald (4.0.1) Ændret adfærd Håndtér documentsDropped, eller opdel uploads.
create, join Layoutene CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS og VIDEO_FOCUS fjernet Ændret adfærd Brug UNIFIED_LAYOUT eller et af de særlige layouts.
create, join Nye parametre lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation Nyt Valgfrit.
end Afslutter også grupperum, der er oprettet via API'et Ændret adfærd Fjern midlertidige løsninger, der afsluttede isBreakout-rum separat.
insertDocument Begrænsning af anmodningsfrekvens og nye fejlnøgler (4.0.1) Ændret adfærd Håndter rateLimitExceeded og de nye messageKey-værdier.
join fullName er begrænset til 255 tegn Bagudinkompatibel ændring Afkort navne; håndter fullNameTooLong.
join webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction og userdata-bbb_parent_room_moderator er fjernet Ændret adfærd Erstat som beskrevet nedenfor.
sendChatMessage Nye fejlnøgler for manglende parametre Ændret adfærd Håndter missingParamMeetingID og missingParamMessage.
/api/rest/clientSettings Slutpunkt fjernet Bagudinkompatibel ændring Kald det ikke længere; brug clientSettingsOverride til at tilpasse klientindstillingerne.

Ændringer i create

Fjernede parametre

Parameter (3.x) Status i 4.x Erstatning
lockSettingsDisableNote Fjernet (var et forældet alias). Bagudinkompatibel ændring lockSettingsDisableNotes
sharedNotesEditor Ignoreres. Etherpad er fjernet, og alle møder bruger BlockNote. Ingen. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown og sharedNotesInitialContentMarkdownUrl virker nu for alle møder – ikke længere kun med sharedNotesEditor=blockNote.
copyright Fjernet. Værdien blev aldrig sendt videre til klienten. Klientindstillingen public.app.copyright via clientSettingsOverride (kræver allowOverrideClientSettingsOnCreateCall=true på serveren) eller clientSettingsOverrideJsonUrl.
logoutTimer Fjernet. Værdien blev aldrig sendt videre til klienten. —
webVoice Fjernet. Forældet, siden Flash-klienten blev udfaset i BBB 2.3. voiceBridge
Før (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
Efter (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Layouts

Layoutvalget i klienten er erstattet af ét adaptivt layout. UNIFIED_LAYOUT er den nye standardværdi for meetingLayout, og de klassiske layouts accepteres ikke længere af meetingLayout (på create), enforceLayout (på join og getJoinUrl) og userdata-bbb_default_layout:

Fjernede layoutværdier udløser ikke en fejl: Klienten ignorerer dem og bruger i stedet den næste layoutkilde (f.eks. mødets layout eller standardlayoutet).

Værdi i 3.x Status i 4.x Anbefalet værdi i 4.x
CUSTOM_LAYOUT (standard i 3.x) Fjernet UNIFIED_LAYOUT
SMART_LAYOUT Fjernet UNIFIED_LAYOUT
PRESENTATION_FOCUS Fjernet UNIFIED_LAYOUT; til en skærm, der kun viser præsentationen (f.eks. en projektor), PRESENTATION_ONLY
VIDEO_FOCUS Fjernet UNIFIED_LAYOUT; til en kameravæg CAMERAS_ONLY
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY Uændret —

CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY og MEDIA_ONLY er særlige layouts til hybrid- eller kioskscenarier – de skjuler store dele af brugergrænsefladen. Brug dem ikke som en direkte erstatning for de fjernede layouts i almindelige møder.

Mediebroer

audioBridge, cameraBridge og screenShareBridge har nu livekit som standardværdi i stedet for bbb-webrtc-sfu. Værdien freeswitch er ikke længere gyldig for audioBridge: Klienten behandler den som en ukendt bro og bruger nu livekit som reserve (tidligere bbb-webrtc-sfu). Brug audioBridge=bbb-webrtc-sfu i stedet.

Deltagere, der ringer ind via telefon til LiveKit-lydbroen, springer gæsteventeværelset over, selv med guestPolicy=ASK_MODERATOR. Hvis din integration er afhængig af, at moderatorer lukker telefondeltagere ind, skal du angive audioBridge=bbb-webrtc-sfu i create, hvilket skifter lydbroen til FreeSWITCH.

Bemærkning til bbbserver.de-kunder: Vi arbejder på at bevare BigBlueButtons adgangsbegrænsning for telefondeltagere, også når LiveKit bruges.

userdata-parametrene userdata-bbb_listen_only_mode og userdata-bbb_transparent_listen_only evalueres kun med audioBridge=bbb-webrtc-sfu. Med livekit tilsluttes brugere, der kun lytter, altid via en mikrofonforbindelse med mikrofonen slået fra.

disabledFeatures-værdier

Værdi Ændring
layouts Ikke længere gyldig – layoutvalget er fjernet fra klienten. Ingen funktionel påvirkning
captions Ikke længere gyldig – har ikke haft nogen virkning siden BBB 3.0. Brug liveTranscription til at deaktivere automatisk transskription. Ingen funktionel påvirkning
pinChatMessage Nyt: deaktiverer fastgørelse af chatbeskeder. Nyt
multiFunctionalMode Nyt: deaktiverer det ekstra sidepanel. Nyt
webcamGrid Nyt: deaktiverer avatarfelterne for brugere uden kamera, mens præsentationen er minimeret. Nyt

Forhåndsuploadede præsentationer

Fra og med BBB 4.0.1 uploader et create-kald højst 10 dokumenter (serverindstillingen maxPresentationsPerRequest; standardpræsentationen tælles ikke med). Dokumentet markeret med current="true" beholdes altid, og de øvrige følger i anmodningens rækkefølge. Overskydende dokumenter udelades, men mødet oprettes stadig, og svaret indeholder messageKey=documentsDropped:

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>demo</meetingID>
  <!-- ... -->
  <messageKey>documentsDropped</messageKey>
  <message>...</message>
</response>

Bemærk, at messageKey nu kan være documentsDropped på SUCCESS. Hvis din kode behandler enhver messageKey som en fejl eller kun kontrollerer for duplicateWarning, skal du tilpasse den. Upload yderligere dokumenter bagefter med insertDocument.

Desuden kontrollerer create nu anmodningens indhold, før mødet oprettes: Indhold, der ikke er velformet XML, afvises med messageKey=malformedXml, og en dokument-URL med ugyldig syntaks afvises med messageKey=invalidPresentationUrl. I begge tilfælde oprettes mødet ikke.

Callback ved mødeafslutning

Siden BBB 4.0.1 føjer meetingEndedURL-callbacken meetingID og recordingmarks til forespørgselsstrengen i din URL (4.0.0 kaldte URL'en uændret). Eksisterende parametre bevarer deres værdier, men kan blive kodet på ny. Hvis din URL allerede indeholder en parameter med samme navn, sendes begge værdier – din først.

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

Hvis du stadig bruger meta_endCallbackUrl: Den officielle dokumentation anbefaler nu meetingEndedURL i stedet, fordi meta_*-værdier kan blive synlige for brugerne i mødet og dermed afsløre hemmelige tokens i callback-URL'en. Verificer ikke en signatur ud fra den rå forespørgselsstreng, da den kan blive kodet på ny.

Andre ændringer

  • Grupperum, der oprettes i klienten, arver nu den gældende meetingKeepEvents-værdi fra deres overordnede møde (tidligere brugte de altid serverens standardværdi defaultKeepEvents). Grupperum, som du selv opretter via create med isBreakout=true, bruger stadig deres egen meetingKeepEvents-parameter.

Nye parametre

Parameter Standard Beskrivelse
lockSettingsPresenterPolicy requireApproval Politik for "Anmod om at præsentere": moderatorOnly, requireApproval eller freeForAll.
requireUserConsentBeforeUnmuting false Med true skal brugerne give samtykke, før en moderator slår deres mikrofon til (kun relevant med allowModsToUnmuteUsers=true).

Standardværdien requireApproval betyder, at tilskuere nu kan anmode om præsentationsværtsrollen i klienten. Hvis kun moderatorer skal kunne tildele præsentationsværtsrollen, skal du angive lockSettingsPresenterPolicy=moderatorOnly.

Alle detaljer: Opret møde (4.x).

Ændringer i join

Parameter Ændring Hvad du skal gøre
fullName Begrænset til 255 tegn. Længere værdier afvises med fullNameTooLong (tidligere ubegrænset). Afkort visningsnavne, før du opbygger URL'en til deltagelse.
enforceLayout Kun UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY og MEDIA_ONLY accepteres. Erstat gamle værdier som vist i layouttabellen ovenfor.
webVoiceConf Fjernet (værdien blev aldrig læst). Fjern parameteren.
userdata-bbb_change_layout Fjernet; værdierne smart, videoFocus, presentationFocus og custom findes ikke længere. Brug userdata-bbb_default_layout.
userdata-enable-user-reaction Fjernet. Brug disabledFeatures=userReactions på create eller klientindstillingen public.userReaction.enabled.
userdata-bbb_parent_room_moderator Fjernet i 4.0.1; den havde ingen effekt siden 3.0.25. Tildel rollen i grupperummet med role.
userdata-bbb_hide_sidebar_navigation Nyt: Lukker sidebjælkens navigation og panel, når man deltager. Nyt Valgfrit.
Før (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Efter (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Ændringer i insertDocument

  • Højst 10 dokumenter pr. kald (maxPresentationsPerRequest). Overskydende dokumenter udelades, og svaret er stadig SUCCESS med messageKey=documentsDropped.
  • Begrænsning af kald pr. møde: Som standard 30 kald pr. 60 sekunder. Kald over grænsen afvises med rateLimitExceeded – prøv igen efter en pause.
  • Hvert FAILED-svar indeholder nu en messageKey: notFound, malformedXml, invalidPresentationUrl, invalidFilename, presentationDisabled, noDocuments.

Hvis din fejlhåndtering sammenligner message-teksten, skal du skifte til messageKey. Detaljer: Indsæt præsentation (4.x).

Ændringer i end

Afslutning af et møde afslutter nu også alle dets grupperum, herunder rum oprettet via create med isBreakout=true. Tidligere blev kun grupperum oprettet fra klienten afsluttet sammen med deres overordnede møde. Hvis din applikation afsluttede sådanne rum med separate end-kald, er disse kald ikke længere nødvendige – sørg for, at din kode kan håndtere et grupperum, der allerede er afsluttet.

Ændringer i sendChatMessage

messageKey for manglende parametre er ændret: En manglende message returnerer nu missingParamMessage (tidligere nullError), og en manglende meetingID returnerer missingParamMeetingID (tidligere meetingNotFound). Overskridelser af længdegrænsen returnerer stadig sizeError, og ugyldige tegn i meetingID returnerer stadig validationError.

Fjernede endepunkter og ændringer på HTTP-niveau

  • /api/rest/clientSettings er fjernet. Klientindstillinger leveres nu via GraphQL inde i klienten; tilpas dem pr. møde med clientSettingsOverride eller clientSettingsOverrideJsonUrl.
  • De Etherpad-relaterede dele af GraphQL-API'et er fjernet. Plugins eller integrationer, der forespørger dem, modtager en valideringsfejl.
  • Ukendte URL'er under /bigbluebutton/ returnerer 404 med JSON som svarindhold i stedet for et XML-dokument.
  • Anmodninger med mere end 10,000 parametre besvares med HTTP 500.
  • CORS-preflight-anmodninger uden CORS-konfiguration returnerer 200 uden Access-Control-*-headere (tidligere 403); Vary: Origin sendes ikke længere.
  • Alle svar indeholder sikkerhedsheaderne X-Frame-Options, X-Content-Type-Options, Referrer-Policy og X-XSS-Protection. Hvis du indlejrer API-svar i rammer, skal du kontrollere X-Frame-Options.

Ændringerne af 404-svar, parametergrænsen og CORS-preflight-anmodninger gælder allerede siden BBB 3.0.40 (bbb-web på Grails 8); de påvirker dig kun, hvis dine servere kører en ældre 3.0-udgave. Sikkerhedsheaderne er nye i 4.0 – på BBB 3.0.40 er de deaktiveret.

Uændret

Følgende dele af API'et er identiske i 3.x og 4.x – der kræves ingen ændringer:

  • Beregning af Checksum og understøttede hash-algoritmer (SHA-1, SHA-256, SHA-384, SHA-512)
  • isMeetingRunning, getMeetings, getMeetingInfo (Parametre og svarformat)
  • getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack
  • Webhooks, bortset fra pad-content-hændelsen, som ikke længere findes, fordi Etherpad er fjernet
  • Rolletildeling via role på join (indført i BBB 2.4)

Serverindstillinger, der påvirker API'ets adfærd

Disse indstillinger konfigureres af serveroperatøren i bbb-web.properties, ikke via API-parametre. Hvis du driver dine egne servere, eller din udbyder ændrer indstillingerne, kan adfærden for dine API-kald ændre sig:

Indstilling Ændring i 4.x
allowDuplicateExtUserid Fjernet. Flere tilslutninger med samme userID styres nu af maxUserConcurrentAccesses.
defaultMeetingLayout Standardværdi UNIFIED_LAYOUT (tidligere CUSTOM_LAYOUT).
audioBridge, cameraBridge, screenShareBridge Standard: livekit.
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec Nye grænser (standardværdier: 10, 30, 60).
accessControlAllowOrigin Fjernet; CORS konfigureres via grails.cors.*.

Tjekliste til migrering

Søg efter fjernede værdier i din kode: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction og clientSettings.

Ryd op i disabledFeatures: fjern layouts og captions.

Begræns visningsnavne til 255 tegn, og håndter fullNameTooLong.

Kontrollér upload af præsentationer: højst 10 dokumenter pr. create/insertDocument-kald, og håndter documentsDropped og rateLimitExceeded.

Gennemgå din callback-handler for meetingEndedURL: den skal acceptere de ekstra parametre meetingID og recordingmarks.

Tag stilling til nye standardværdier: anmodninger om præsentationsrollen (lockSettingsPresenterPolicy) og gæsteventeværelset for telefondeltagere (audioBridge).

Test mod en 4.x-server – især grupperum, upload af præsentationer og din fejlhåndtering baseret på messageKey.

Skal din integration understøtte begge versioner i en periode? Alle ovenstående ændringer er bagudkompatible i én retning: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout og visningsnavne på højst 255 tegn fungerer også på BBB 3.0.19+-servere. Brug dem overalt, så fungerer dine API-kald på begge versioner.

Leder du efter den tidligere dokumentation? Den komplette 3.x-reference er stadig tilgængelig, f.eks. Opret møde (3.x).

Ofte stillede spørgsmål

Du kan – og bør – gøre det på forhånd. De anbefalede erstatninger (UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) understøttes allerede af BBB 3.0.19. Forbered din kode, så serveropgraderingen ikke kræver en samtidig udgivelse af din applikation.

Nej. BigBlueButton ignorerer ukendte parametre, så en fjernet parameter har ingen effekt, uden at der gives besked om det. Derfor er fjernede parametre nemme at overse – kontrollér din kode i forhold til listerne i denne vejledning.

Nej. checksum beregnes stadig som sha(apiCallName + queryString + sharedSecret) med de samme understøttede hash-algoritmer.

Nej. Denne vejledning dækker kun ændringer i de API-kald, som din applikation foretager. Opgradering af selve konferenceserverne er et separat emne og håndteres af din serveroperatør.