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 |
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
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.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoHvis 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ærdidefaultKeepEvents). Grupperum, som du selv opretter viacreatemedisBreakout=true, bruger stadig deres egenmeetingKeepEvents-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. |
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Ændringer i insertDocument
- Højst 10 dokumenter pr. kald (
maxPresentationsPerRequest). Overskydende dokumenter udelades, og svaret er stadigSUCCESSmedmessageKey=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 enmessageKey: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/clientSettingser fjernet. Klientindstillinger leveres nu via GraphQL inde i klienten; tilpas dem pr. møde medclientSettingsOverrideellerclientSettingsOverrideJsonUrl.- 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/returnerer404med 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
200udenAccess-Control-*-headere (tidligere403);Vary: Originsendes ikke længere. - Alle svar indeholder sikkerhedsheaderne
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyogX-XSS-Protection. Hvis du indlejrer API-svar i rammer, skal du kontrollereX-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
rolepå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
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.sha(apiCallName + queryString + sharedSecret) med de samme understøttede hash-algoritmer.