Versione API: 4.x più recente 3.x
Capitolo 2

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

Layout

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.

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

Se 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 meetingKeepEvents della riunione principale (in precedenza usavano sempre il valore predefinito del server defaultKeepEvents). Le stanze per gruppi di lavoro che crei direttamente tramite create con isBreakout=true continuano a usare il proprio parametro meetingKeepEvents.

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.
Prima (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Dopo (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Modifiche a insertDocument

  • Al massimo 10 documenti per chiamata (maxPresentationsPerRequest). I documenti in eccesso vengono scartati; la risposta rimane SUCCESS con messageKey=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 FAILED ora include un messageKey: 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 con clientSettingsOverride o clientSettingsOverrideJsonUrl.
  • 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/ restituiscono 404 con 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 200 senza intestazioni Access-Control-* (in precedenza 403); Vary: Origin non viene più inviato.
  • Tutte le risposte includono le intestazioni di sicurezza X-Frame-Options, X-Content-Type-Options, Referrer-Policy e X-XSS-Protection. Se incorpori le risposte API in frame, controlla X-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 role su join (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

Puoi, e dovresti, farlo in anticipo. Le alternative consigliate (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.

No. BigBlueButton ignora i parametri sconosciuti, quindi un parametro rimosso non ha alcun effetto e non genera segnalazioni. Per questo è facile non accorgersi dei parametri rimossi: confronta il tuo codice con gli elenchi di questa guida.

No. Il checksum viene ancora calcolato come sha(apiCallName + queryString + sharedSecret) con gli stessi algoritmi di hash supportati.

No. Questa guida tratta esclusivamente le modifiche alle chiamate API effettuate dalla tua applicazione. L'aggiornamento dei server di conferenza è un argomento separato ed è gestito dal responsabile del tuo server.