Hoofdstuk 19

userdata – Clientinstellingen

Met userdata-parameters kun je client-side instellingen per gebruiker overschrijven door parameters met het voorvoegsel userdata- toe te voegen aan de API-call join. Zo kun je de BigBlueButton-ervaring voor individuele deelnemers aanpassen zonder de serverconfiguratie te wijzigen.

De lijst met beschikbare userdata-parameters wordt slechts gedeeltelijk behandeld in de officiële BigBlueButton-documentatie. Veel parameters zijn afgeleid uit broncodeanalyse van settings.yml en kunnen tussen versies zonder aankondiging veranderen. undocumented

Hoe userdata-parameters werken

Userdata-parameters worden als URL-queryparameters doorgegeven in de request join. Ze overschrijven de standaardwaarden uit settings.yml alleen voor die ene gebruikerssessie. De parameternamen beginnen altijd met het voorvoegsel userdata- gevolgd door de instellingssleutel. 

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

Omdat userdata-parameters deel uitmaken van de querystring, worden ze meegenomen in de checksum-berekening. Zorg ervoor dat je ze toevoegt voordat je de checksum berekent, niet erna.

Audio- en mediaparameters

Parameter Type Standaard Beschrijving
userdata-bbb_auto_join_audio Boolean — Automatisch deelnemen aan de audiobrug wanneer de gebruiker de vergadering betreedt.
userdata-bbb_listen_only_mode Boolean — Schakel listen-only-modus voor de gebruiker in of uit.
userdata-bbb_force_listen_only Boolean — Dwing de gebruiker in listen-only-modus. Dit geldt niet voor moderators.
userdata-bbb_skip_check_audio Boolean — Sla het dialoogvenster voor de audiotest over bij het deelnemen.
userdata-bbb_skip_echotest_if_previous_device Boolean — Sla de echotest over als hetzelfde audioapparaat als in de vorige sessie wordt gedetecteerd.

Webcamparameters

Parameter Type Standaard Beschrijving
userdata-bbb_auto_share_webcam Boolean — Start automatisch het delen van de webcam wanneer de gebruiker deelneemt.
userdata-bbb_mirror_own_webcam Boolean — Spiegel de voorbeeldweergave van de eigen webcam van de gebruiker horizontaal.

Parameters voor lay-out en weergave

Parameter Type Standaard Beschrijving
userdata-bbb_auto_swap_layout Boolean — Wissel automatisch van lay-out wanneer een presentatie wordt gedeeld.
userdata-bbb_default_layout String — Stel de standaardlay-out voor de gebruiker in. De beschikbare waarden zijn afhankelijk van de clientconfiguratie. undocumented
userdata-bbb_hide_presentation Boolean — Verberg het presentatiegebied voor de gebruiker.
userdata-bbb_prefer_dark_theme Boolean — Activeer het donkere thema voor de gebruikersinterface.

Parameters voor aanpassing en branding

Parameter Type Standaard Beschrijving
userdata-bbb_custom_style String — Inline-CSS-regels (URL-gecodeerd) toegepast op de BigBlueButton-client voor deze gebruiker.
userdata-bbb_custom_style_url URL — URL naar een extern CSS-bestand dat door de client wordt geladen voor aangepaste styling. Moet via HTTPS worden aangeboden.

De parameter userdata-bbb_custom_style kan worden misbruikt voor cross-site scripting als join-URL's client-side worden opgebouwd. Genereer join-URL's altijd op de server, waar je controle hebt over de parameterwaarden.

Parameters voor UI-elementen

Parameter Type Standaard Beschrijving
userdata-bbb_hide_notifications Boolean — Verberg meldingspop-ups in de clientinterface.
userdata-bbb_hide_controls Boolean — Verberg de UI-bedieningselementen (werkbalkknoppen) voor de gebruiker.
userdata-bbb_shortcuts String — Definieer aangepaste sneltoetsen voor de gebruiker.

Parameters voor opname en externe besturing

Parameter Type Standaard Beschrijving
userdata-bbb_outside_toggle_recording Boolean — Sta een externe applicatie toe om de opname van de vergadering in en uit te schakelen.
userdata-bbb_outside_toggle_self_voice Boolean — Sta een externe applicatie toe om de audio van de gebruiker in en uit te schakelen.

Whiteboard-parameters

Parameter Type Standaard Beschrijving
userdata-bbb_initial_selected_tool String — Stel het aanvankelijk geselecteerde whiteboard-gereedschap in wanneer de gebruiker het whiteboard opent. De geaccepteerde waarden worden bepaald door de clientconfiguratie. undocumented

Praktische voorbeelden

Hieronder staan veelvoorkomende combinaties van userdata-parameters voor typische gebruikssituaties.

Kioskmodus

Ideaal voor schermen in vergaderruimtes of digital signage waarbij geen gebruikersinteractie vereist is: 

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

Tenant-specifieke branding

Pas een aangepaste CSS-stylesheet toe per tenant of klant: 

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

Toegankelijke snelle deelname

Vereenvoudig het deelnameproces voor gebruikers die een eenvoudige, toegankelijke ervaring nodig hebben: 

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

Belangrijke opmerkingen

  • Userdata-parameters hebben alleen invloed op de huidige sessie van de individuele gebruiker. Ze wijzigen de standaardinstellingen van de server niet.
  • Niet alle parameters zijn beschikbaar in elke BigBlueButton-versie. Test tegen je doelversie voordat je uitrolt.
  • CSS geladen via userdata-bbb_custom_style_url moet via HTTPS worden aangeboden.

Bij gebruik van het endpoint getJoinUrl worden bepaalde userdata-parameters voor kijkers (rol VIEWER) geblokkeerd als beveiligingsmaatregel. De blokkeerlijst wordt server-side geconfigureerd via de eigenschap getJoinUrlUserdataBlocklist in bigbluebutton.properties. Dit voorkomt dat kijkers beveiligingskritieke clientinstellingen overschrijven via vooraf ondertekende join-URL's. undocumented

Veelgestelde vragen

Nee. Userdata-parameters worden alleen toegepast op de enkele sessie die door de call join wordt gestart. Als de gebruiker vertrekt en opnieuw deelneemt, moeten de parameters opnieuw in de nieuwe join-URL worden opgenomen.

Nee. Userdata-parameters zijn uitsluitend bedoeld voor het endpoint join. Ze worden door de client verwerkt wanneer een gebruiker aan een vergadering deelneemt en hebben geen effect op de call create.

Ja. Omdat ze deel uitmaken van de URL-querystring, worden ze meegenomen in de checksum-berekening. Je moet alle userdata-parameters aan de querystring toevoegen voordat je de checksum berekent.

Nee. De parameter userdata-bbb_force_listen_only geldt alleen voor kijkers. Moderators worden ongeacht deze instelling niet gedwongen in listen-only-modus.

De officiële documentatie behandelt slechts een subset. De meest complete en actuele lijst staat in het bestand settings.yml binnen de broncode van de BigBlueButton-client. Nieuwe parameters worden vaak toegevoegd zonder updates van de documentatie.