Capitolo 19

userdata – Impostazioni client

I parametri userdata ti permettono di sovrascrivere le impostazioni lato client per singolo utente aggiungendo parametri con prefisso userdata- alla chiamata API join. Questo ti consente di personalizzare l'esperienza BigBlueButton per i singoli partecipanti senza modificare la configurazione del server.

L'elenco dei parametri userdata disponibili è coperto solo parzialmente dalla documentazione ufficiale di BigBlueButton. Molti parametri derivano dall'analisi del codice sorgente di settings.yml e possono cambiare tra versioni senza preavviso. undocumented

Come funzionano i parametri userdata

I parametri userdata vengono passati come parametri di query URL nella richiesta join. Sovrascrivono i valori predefiniti di settings.yml solo per quella singola sessione utente. I nomi dei parametri iniziano sempre con il prefisso userdata- seguito dalla chiave dell'impostazione. 

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&userdata-bbb_auto_join_audio=true&userdata-bbb_skip_check_audio=true&checksum=replace-with-checksum

Poiché i parametri userdata fanno parte della query string, sono inclusi nel calcolo del checksum. Assicurati di aggiungerli prima di calcolare il checksum, non dopo.

Parametri audio e multimediali

Parametro Tipo Predefinito Descrizione
userdata-bbb_auto_join_audio Boolean — Accedi automaticamente al bridge audio quando l'utente entra nella riunione.
userdata-bbb_listen_only_mode Boolean — Abilita o disabilita la modalità listen-only per l'utente.
userdata-bbb_force_listen_only Boolean — Forza l'utente in modalità listen-only. Questo non si applica ai moderatori.
userdata-bbb_skip_check_audio Boolean — Salta la finestra di dialogo del test audio all'accesso.
userdata-bbb_skip_echotest_if_previous_device Boolean — Salta il test eco se viene rilevato lo stesso dispositivo audio della sessione precedente.

Parametri webcam

Parametro Tipo Predefinito Descrizione
userdata-bbb_auto_share_webcam Boolean — Avvia automaticamente la condivisione della webcam quando l'utente entra.
userdata-bbb_mirror_own_webcam Boolean — Rispecchia orizzontalmente l'anteprima della webcam dell'utente.

Parametri di layout e visualizzazione

Parametro Tipo Predefinito Descrizione
userdata-bbb_auto_swap_layout Boolean — Scambia automaticamente il layout quando viene condivisa una presentazione.
userdata-bbb_default_layout String — Imposta il layout predefinito per l'utente. I valori disponibili dipendono dalla configurazione del client. undocumented
userdata-bbb_hide_presentation Boolean — Nascondi l'area della presentazione all'utente.
userdata-bbb_prefer_dark_theme Boolean — Attiva il tema scuro per l'interfaccia utente.

Parametri di personalizzazione e branding

Parametro Tipo Predefinito Descrizione
userdata-bbb_custom_style String — Regole CSS inline (codificate URL) applicate al client BigBlueButton per questo utente.
userdata-bbb_custom_style_url URL — URL di un file CSS esterno caricato dal client per uno stile personalizzato. Deve essere servito tramite HTTPS.

Il parametro userdata-bbb_custom_style può essere sfruttato per cross-site scripting se gli URL join vengono costruiti lato client. Genera sempre gli URL join sul server, dove controlli i valori dei parametri.

Parametri degli elementi dell'interfaccia

Parametro Tipo Predefinito Descrizione
userdata-bbb_hide_notifications Boolean — Nascondi i popup di notifica nell'interfaccia del client.
userdata-bbb_hide_controls Boolean — Nascondi gli elementi di controllo dell'interfaccia utente (pulsanti della barra degli strumenti) all'utente.
userdata-bbb_shortcuts String — Definisci scorciatoie da tastiera personalizzate per l'utente.

Parametri di registrazione e controllo esterno

Parametro Tipo Predefinito Descrizione
userdata-bbb_outside_toggle_recording Boolean — Consenti a un'applicazione esterna di attivare e disattivare la registrazione della riunione.
userdata-bbb_outside_toggle_self_voice Boolean — Consenti a un'applicazione esterna di attivare e disattivare l'audio dell'utente.

Parametri della lavagna

Parametro Tipo Predefinito Descrizione
userdata-bbb_initial_selected_tool String — Imposta lo strumento della lavagna selezionato inizialmente quando l'utente apre la lavagna. I valori accettati sono determinati dalla configurazione del client. undocumented

Esempi pratici

Di seguito sono riportate combinazioni comuni di parametri userdata per casi d'uso tipici.

Modalità kiosk

Ideale per schermi di sale conferenze o segnaletica digitale dove non è richiesta alcuna interazione dell'utente: 

userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true

Branding specifico del tenant

Applica un foglio di stile CSS personalizzato per tenant o cliente: 

userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css

Accesso rapido accessibile

Semplifica il processo di accesso per gli utenti che necessitano di un'esperienza semplificata e accessibile: 

userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true

Note importanti

  • I parametri userdata influenzano solo la sessione corrente del singolo utente. Non modificano le impostazioni predefinite del server.
  • Non tutti i parametri sono disponibili in ogni versione di BigBlueButton. Verifica rispetto alla tua versione di destinazione prima del deployment.
  • CSS caricato tramite userdata-bbb_custom_style_url deve essere servito tramite HTTPS.

Quando usi l'endpoint getJoinUrl, alcuni parametri userdata sono bloccati per i viewer (ruolo VIEWER) come misura di sicurezza. La blocklist è configurata lato server tramite la proprietà getJoinUrlUserdataBlocklist in bigbluebutton.properties. Questo impedisce ai viewer di sovrascrivere impostazioni client critiche per la sicurezza tramite URL join prefirmati. undocumented

Domande frequenti

No. I parametri userdata si applicano solo alla singola sessione avviata dalla chiamata join. Se l'utente esce e rientra, i parametri devono essere inclusi di nuovo nel nuovo URL join.

No. I parametri userdata sono progettati solo per l'endpoint join. Vengono elaborati dal client quando un utente entra in una riunione e non hanno alcun effetto sulla chiamata create.

Sì. Poiché fanno parte della query string dell'URL, sono inclusi nel calcolo del checksum. Devi aggiungere tutti i parametri userdata alla query string prima di calcolare il checksum.

No. Il parametro userdata-bbb_force_listen_only si applica solo ai viewer. I moderatori non vengono forzati in modalità listen-only indipendentemente da questa impostazione.

La documentazione ufficiale copre solo un sottoinsieme. L'elenco più completo e aggiornato si trova nel file settings.yml all'interno del codice sorgente del client BigBlueButton. Nuovi parametri vengono aggiunti frequentemente senza aggiornamenti della documentazione.