Migrare dalla versione 3.x alla 4.x
BigBlueButton 4.0 rimuove diversi parametri e valori di layout deprecati, modifica vari valori predefiniti e introduce nuove chiavi di errore. Questa guida elenca tutto ciò che devi verificare nelle chiamate API quando la tua integrazione comunica con un server BigBlueButton 4.x anziché con un server BigBlueButton 3.x.
Ambito: questa guida tratta le modifiche alle chiamate API effettuate dalla tua applicazione (create, join, insertDocument, …). Non tratta l'aggiornamento o la migrazione dei server di conferenza stessi.
Prima le buone notizie: gli endpoint, il calcolo di checksum, il formato di risposta XML e tutti gli endpoint delle registrazioni rimangono invariati. Per la maggior parte delle integrazioni è sufficiente modificare pochi parametri. I parametri sconosciuti o rimossi vengono ignorati senza alcuna segnalazione: un parametro rimosso, quindi, non causa errori, ma non ha più alcun effetto.
Panoramica di tutte le modifiche
| Endpoint | Modifica | Impatto | Azione richiesta |
|---|---|---|---|
create | lockSettingsDisableNote (singolare) rimosso | Modifica incompatibile | Usa lockSettingsDisableNotes. |
create | Il bridge multimediale predefinito è ora livekit | Modifica del comportamento | Verifica l'accesso telefonico con la sala d'attesa degli ospiti; imposta audioBridge se necessario. |
create | sharedNotesEditor ignorato: Etherpad rimosso | Modifica del comportamento | Rimuovi il parametro; le note condivise utilizzano sempre BlockNote. |
create | meetingEndedURL riceve meetingID e recordingmarks (4.0.1) | Modifica del comportamento | Assicurati che il gestore del callback accetti i parametri aggiuntivi. |
create | Le sale per gruppi create nel client ereditano meetingKeepEvents dalla riunione principale | Modifica del comportamento | In genere nessuna. |
create | Il valore predefinito di meetingLayout è ora UNIFIED_LAYOUT | Modifica del comportamento | In genere nessuna; passa esplicitamente meetingLayout per utilizzare uno dei layout speciali. |
create | Nuove chiavi di errore malformedXml e invalidPresentationUrl; la riunione non viene creata | Modifica del comportamento | Verifica la gestione degli errori per i documenti precaricati. |
create | layouts e captions rimossi da disabledFeatures | Nessun impatto funzionale | Rimuovi i valori dal tuo elenco. |
create | copyright, logoutTimer, webVoice rimossi | Nessun impatto funzionale | Rimuovi i parametri (non avevano alcun effetto neanche prima). |
create, insertDocument | Massimo 10 documenti per chiamata (4.0.1) | Modifica del comportamento | Gestisci documentsDropped oppure suddividi i caricamenti. |
create, join | Layout CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS e VIDEO_FOCUS rimossi | Modifica del comportamento | Usa UNIFIED_LAYOUT o uno dei layout speciali. |
create, join | Nuovi parametri lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation | Novità | Facoltativo. |
end | Termina anche le stanze per sottogruppi create tramite l'API | Modifica del comportamento | Rimuovi le soluzioni alternative che terminavano separatamente le stanze isBreakout. |
insertDocument | Limite di frequenza e nuove chiavi di errore (4.0.1) | Modifica del comportamento | Gestisci rateLimitExceeded e i nuovi valori di messageKey. |
join | fullName limitato a 255 caratteri | Modifica incompatibile | Tronca i nomi; gestisci fullNameTooLong. |
join | webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction e userdata-bbb_parent_room_moderator rimossi | Modifica del comportamento | Sostituisci come descritto di seguito. |
sendChatMessage | Nuove chiavi di errore per i parametri mancanti | Modifica del comportamento | Gestisci missingParamMeetingID e missingParamMessage. |
/api/rest/clientSettings | Endpoint rimosso | Modifica incompatibile | Non chiamarlo più; usa clientSettingsOverride per personalizzare le impostazioni del client. |
Modifiche a create
Parametri rimossi
| Parametro (3.x) | Stato nella versione 4.x | Sostituzione |
|---|---|---|
lockSettingsDisableNote | Rimosso (era un alias deprecato). Modifica incompatibile | lockSettingsDisableNotes |
sharedNotesEditor | Ignorato. Etherpad è stato rimosso; ogni riunione usa BlockNote. | Nessuna. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown e sharedNotesInitialContentMarkdownUrl ora funzionano per ogni riunione, non più solo con sharedNotesEditor=blockNote. |
copyright | Rimosso. Il valore non veniva mai passato al client. | Impostazione del client public.app.copyright tramite clientSettingsOverride (richiede allowOverrideClientSettingsOnCreateCall=true sul server) o clientSettingsOverrideJsonUrl. |
logoutTimer | Rimosso. Il valore non veniva mai passato al client. | — |
webVoice | Rimosso. Obsoleto da quando il client Flash è stato abbandonato nella versione 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_LAYOUTLayout
La selezione del layout nel client è stata sostituita da un unico layout adattivo. UNIFIED_LAYOUT è il nuovo valore predefinito di meetingLayout e i layout classici non sono più accettati da meetingLayout (su create), enforceLayout (su join e getJoinUrl) e userdata-bbb_default_layout:
I valori dei layout rimossi non causano errori: il client li ignora e passa alla fonte di layout successiva (ad esempio il layout della riunione o quello predefinito).
| Valore nella versione 3.x | Stato nella versione 4.x | Valore consigliato nella versione 4.x |
|---|---|---|
CUSTOM_LAYOUT (predefinito nella versione 3.x) | Rimosso | UNIFIED_LAYOUT |
SMART_LAYOUT | Rimosso | UNIFIED_LAYOUT |
PRESENTATION_FOCUS | Rimosso | UNIFIED_LAYOUT; per uno schermo dedicato alla sola presentazione (ad esempio un proiettore) PRESENTATION_ONLY |
VIDEO_FOCUS | Rimosso | UNIFIED_LAYOUT; per una griglia di webcam CAMERAS_ONLY |
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY | Invariato | — |
CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY e MEDIA_ONLY sono layout speciali per scenari ibridi o in modalità chiosco: nascondono ampie parti dell'interfaccia utente. Non usarli come sostituti diretti dei layout rimossi nelle riunioni normali.
Bridge multimediali
audioBridge, cameraBridge e screenShareBridge ora hanno come valore predefinito livekit anziché bbb-webrtc-sfu. Il valore freeswitch non è più valido per audioBridge: il client lo tratta come un bridge sconosciuto e ora ripiega su livekit (in precedenza bbb-webrtc-sfu). Usa invece audioBridge=bbb-webrtc-sfu.
I partecipanti che si collegano telefonicamente al bridge audio LiveKit saltano la sala d'attesa degli ospiti, anche con guestPolicy=ASK_MODERATOR. Se la tua integrazione prevede che siano i moderatori ad ammettere i partecipanti telefonici, passa audioBridge=bbb-webrtc-sfu su create, che imposta il bridge audio su FreeSWITCH.
Nota per i clienti bbbserver.de: stiamo lavorando per mantenere la restrizione di accesso telefonico di BigBlueButton anche quando si utilizza LiveKit.
I parametri di userdata, userdata-bbb_listen_only_mode e userdata-bbb_transparent_listen_only, vengono valutati solo con audioBridge=bbb-webrtc-sfu. Con livekit, gli utenti in modalità solo ascolto si connettono sempre tramite una connessione con microfono disattivato.
Valori di disabledFeatures
| Valore | Modifica |
|---|---|
layouts | Non più valido: la selezione del layout è stata rimossa dal client. Nessun impatto funzionale |
captions | Non più valido: non aveva alcun effetto dalla versione BBB 3.0. Usa liveTranscription per disabilitare la trascrizione automatica. Nessun impatto funzionale |
pinChatMessage | Novità: disabilita la possibilità di fissare i messaggi della chat. Novità |
multiFunctionalMode | Novità: disabilita il pannello laterale ausiliario. Novità |
webcamGrid | Novità: disabilita i riquadri degli avatar degli utenti senza webcam quando la presentazione è ridotta a icona. Novità |
Presentazioni precaricate
A partire dalla versione BBB 4.0.1, una chiamata a create carica al massimo 10 documenti (impostazione del server maxPresentationsPerRequest; la presentazione predefinita non viene conteggiata). Il documento contrassegnato come current="true" viene sempre mantenuto; gli altri seguono nell'ordine della richiesta. I documenti in eccesso vengono scartati, ma la riunione viene comunque creata e la risposta contiene messageKey=documentsDropped:
<response>
<returncode>SUCCESS</returncode>
<meetingID>demo</meetingID>
<!-- ... -->
<messageKey>documentsDropped</messageKey>
<message>...</message>
</response> Nota che messageKey ora può essere documentsDropped su SUCCESS. Se il tuo codice considera qualsiasi messageKey come un errore o controlla solo duplicateWarning, modificalo. Carica ulteriori documenti in seguito con insertDocument.
Inoltre, create ora controlla il corpo della richiesta prima che la riunione venga creata: un corpo che non contiene XML ben formato genera un errore messageKey=malformedXml, mentre un URL di documento con sintassi non valida genera un errore messageKey=invalidPresentationUrl. In entrambi i casi la riunione non viene creata.
Callback di fine riunione
A partire da BBB 4.0.1, il callback meetingEndedURL aggiunge meetingID e recordingmarks alla stringa di query del tuo URL (4.0.0 chiamava l'URL senza modificarlo). I parametri esistenti mantengono i propri valori, ma potrebbero essere ricodificati. Se il tuo URL contiene già un parametro con lo stesso nome, vengono inviati entrambi i valori, prima il tuo.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoSe usi ancora meta_endCallbackUrl: la documentazione ufficiale ora consiglia di usare meetingEndedURL al suo posto, perché i valori di meta_* potrebbero essere visibili agli utenti della riunione e rivelare token segreti presenti nell'URL di callback. Non verificare una firma sulla stringa di query non elaborata, poiché potrebbe essere ricodificata.
Altre modifiche
- Le stanze per gruppi di lavoro create nel client ora ereditano il valore effettivo di
meetingKeepEventsdella riunione principale (in precedenza usavano sempre il valore predefinito del serverdefaultKeepEvents). Le stanze per gruppi di lavoro che crei direttamente tramitecreateconisBreakout=truecontinuano a usare il proprio parametromeetingKeepEvents.
Nuovi parametri
| Parametro | Predefinito | Descrizione |
|---|---|---|
lockSettingsPresenterPolicy | requireApproval | Criterio «Richiesta di presentare»: moderatorOnly, requireApproval o freeForAll. |
requireUserConsentBeforeUnmuting | false | Con true, gli utenti devono acconsentire prima che un moderatore riattivi il loro microfono (rilevante solo con allowModsToUnmuteUsers=true). |
Il valore predefinito requireApproval significa che gli spettatori ora possono richiedere il ruolo di presentatore nel client. Se solo i moderatori devono poter assegnare il ruolo di presentatore, passa lockSettingsPresenterPolicy=moderatorOnly.
Tutti i dettagli: Crea riunione (4.x).
Modifiche a join
| Parametro | Modifica | Cosa fare |
|---|---|---|
fullName | Limite di 255 caratteri. I valori più lunghi vengono rifiutati con fullNameTooLong (in precedenza non c'era alcun limite). | Tronca i nomi visualizzati prima di costruire l'URL di accesso. |
enforceLayout | Sono accettati solo UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY e MEDIA_ONLY. | Converti i vecchi valori come indicato nella tabella dei layout sopra. |
webVoiceConf | Rimosso (il valore non veniva mai letto). | Rimuovi il parametro. |
userdata-bbb_change_layout | Rimosso; i suoi valori smart, videoFocus, presentationFocus e custom non esistono più. | Usa userdata-bbb_default_layout. |
userdata-enable-user-reaction | Rimosso. | Usa disabledFeatures=userReactions su create oppure l'impostazione del client public.userReaction.enabled. |
userdata-bbb_parent_room_moderator | Rimosso in 4.0.1; non aveva alcun effetto da 3.0.25. | Assegna il ruolo nella stanza per gruppi di lavoro con role. |
userdata-bbb_hide_sidebar_navigation | Novità: chiude la navigazione laterale e il pannello laterale all'accesso. Novità | Facoltativo. |
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_LAYOUTModifiche a insertDocument
- Al massimo 10 documenti per chiamata (
maxPresentationsPerRequest). I documenti in eccesso vengono scartati; la risposta rimaneSUCCESSconmessageKey=documentsDropped. - Limite di frequenza per riunione: per impostazione predefinita, 30 chiamate ogni 60 secondi. Le chiamate oltre il limite falliscono con
rateLimitExceeded: riprova dopo un intervallo di attesa. - Ogni risposta
FAILEDora include unmessageKey:notFound,malformedXml,invalidPresentationUrl,invalidFilename,presentationDisabled,noDocuments.
Se la tua gestione degli errori confronta il testo di message, passa a messageKey. Dettagli: Inserisci presentazione (4.x).
Modifiche a end
La conclusione di una riunione ora termina anche tutte le relative stanze per gruppi di lavoro, comprese quelle create tramite create con isBreakout=true. In precedenza, solo le stanze per gruppi di lavoro create dal client terminavano insieme alla riunione principale. Se la tua applicazione terminava queste stanze con chiamate end separate, tali chiamate non sono più necessarie: assicurati che il tuo codice gestisca correttamente una stanza per gruppi di lavoro già terminata.
Modifiche a sendChatMessage
Il valore di messageKey per i parametri mancanti è cambiato: se manca message, ora viene restituito missingParamMessage (in precedenza nullError); se manca meetingID, viene restituito missingParamMeetingID (in precedenza meetingNotFound). Le violazioni dei limiti di lunghezza continuano a restituire sizeError e i caratteri non validi in meetingID continuano a restituire validationError.
Endpoint rimossi e modifiche a livello HTTP
/api/rest/clientSettingsè stato rimosso. Le impostazioni del client ora vengono fornite tramite GraphQL all'interno del client; personalizzale per ogni riunione conclientSettingsOverrideoclientSettingsOverrideJsonUrl.- Le parti dell'API GraphQL relative a Etherpad sono state rimosse. I plugin o le integrazioni che le interrogano ricevono un errore di convalida.
- Gli URL sconosciuti sotto
/bigbluebutton/restituiscono404con un corpo JSON anziché un documento XML. - Le richieste con più di 10,000 parametri ricevono una risposta
HTTP 500. - Le richieste preliminari CORS in assenza di configurazione CORS restituiscono
200senza intestazioniAccess-Control-*(in precedenza403);Vary: Originnon viene più inviato. - Tutte le risposte includono le intestazioni di sicurezza
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyeX-XSS-Protection. Se incorpori le risposte API in frame, controllaX-Frame-Options.
Le modifiche alle risposte 404, il limite dei parametri e le richieste preliminari CORS si applicano già a partire da BBB 3.0.40 (bbb-web su Grails 8); ti riguardano solo se i tuoi server eseguono una versione 3.0 precedente. Le intestazioni di sicurezza sono una novità di 4.0; su BBB 3.0.40 sono disattivate.
Invariato
Le seguenti parti dell'API sono identiche in 3.x e 4.x: non sono necessarie modifiche:
- Calcolo di Checksum e algoritmi hash supportati (SHA-1, SHA-256, SHA-384, SHA-512)
isMeetingRunning,getMeetings,getMeetingInfo(Parametri e formato della risposta)getRecordings,publishRecordings,deleteRecordings,updateRecordings,getRecordingTextTracks,putRecordingTextTrack- Webhooks, ad eccezione dell'evento
pad-content, che non esiste più perché Etherpad è stato rimosso - Assegnazione del ruolo tramite
rolesujoin(introdotta in BBB 2.4)
Impostazioni del server che influiscono sul comportamento dell'API
Queste impostazioni vengono configurate dall'operatore del server in bbb-web.properties, non tramite parametri API. Se gestisci i tuoi server o il tuo fornitore modifica queste impostazioni, il comportamento delle tue chiamate API potrebbe cambiare:
| Impostazione | Modifica nella versione 4.x |
|---|---|
allowDuplicateExtUserid | Rimosso. Gli accessi multipli con lo stesso userID ora sono controllati da maxUserConcurrentAccesses. |
defaultMeetingLayout | Valore predefinito UNIFIED_LAYOUT (in precedenza CUSTOM_LAYOUT). |
audioBridge, cameraBridge, screenShareBridge | Valore predefinito: livekit. |
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec | Nuovi limiti (valori predefiniti: 10, 30, 60). |
accessControlAllowOrigin | Rimosso; CORS viene configurato tramite grails.cors.*. |
Lista di controllo per la migrazione
Cerca nel tuo codice i valori rimossi: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction e clientSettings.
Ripulisci disabledFeatures: rimuovi layouts e captions.
Limita i nomi visualizzati a 255 caratteri e gestisci fullNameTooLong.
Controlla i caricamenti delle presentazioni: non più di 10 documenti per chiamata create/insertDocument; gestisci documentsDropped e rateLimitExceeded.
Rivedi il tuo gestore di callback per meetingEndedURL: deve accettare i parametri aggiuntivi meetingID e recordingmarks.
Decidi i nuovi valori predefiniti: le richieste di diventare relatore (lockSettingsPresenterPolicy) e la sala d'attesa degli ospiti per i partecipanti che si collegano telefonicamente (audioBridge).
Esegui test con un server 4.x, in particolare per le stanze per gruppi, i caricamenti delle presentazioni e la gestione degli errori basata su messageKey.
La tua integrazione deve supportare entrambe le versioni per un certo periodo? Tutte le modifiche sopra indicate sono compatibili con le versioni precedenti in una sola direzione: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout e i nomi visualizzati di massimo 255 caratteri funzionano anche sui server BBB 3.0.19+. Usali ovunque e le tue chiamate API funzioneranno con entrambe le versioni.
Cerchi la documentazione precedente? La documentazione di riferimento completa di 3.x rimane disponibile, ad esempio Crea riunione (3.x).
Domande frequenti
UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) sono già supportate da BBB 3.0.19. Prepara il tuo codice in modo che l'aggiornamento del server non richieda il rilascio simultaneo di una nuova versione della tua applicazione.sha(apiCallName + queryString + sharedSecret) con gli stessi algoritmi di hash supportati.