API-versie: 4.x nieuwste 3.x

Je bekijkt de API-documentatie voor BigBlueButton 3.x. De huidige versie is BigBlueButton 4.x. Plan je een upgrade? De migratiehandleiding vermeldt alle wijzigingen die je in je API-aanroepen moet aanbrengen.

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.

In BigBlueButton 3.0 staan de userdata-parameters niet in de API-referentie, maar in de beheerdershandleiding (Customize, sectie "Passing user metadata to the client on join"). Parameters kunnen zonder voorafgaande kennisgeving tussen versies veranderen.

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.

Het gedeelte na userdata- mag geen extra koppelteken bevatten – anders wordt de parameter genegeerd. Het voorvoegsel userdata-bbb_ is gereserveerd voor BigBlueButton; integraties die hun eigen gegevens per gebruiker toevoegen, moeten een eigen voorvoegsel gebruiken, bijvoorbeeld userdata-myapp_cohort=2026A. Dergelijke parameters worden bij de gebruiker opgeslagen en naar de opnamegebeurtenissen geschreven, maar door de client genegeerd.

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_default_layout String — Indeling waarin de client start. enforceLayout bij join heeft voorrang; als geen van beide is ingesteld, wordt de indeling van de vergadering gebruikt. Accepteert dezelfde waarden als meetingLayout bij create. BBB 3.0+
userdata-bbb_change_layout Removed in 4.0 String — Verouderde instelling voor het wisselen van indeling. Accepteert dezelfde waarden als meetingLayout bij create (bijvoorbeeld SMART_LAYOUT) en heeft voorrang op userdata-bbb_default_layout. Gebruik in plaats daarvan userdata-bbb_default_layout.
userdata-bbb_hide_presentation_on_join Boolean false Start met het presentatiegebied geminimaliseerd; de gebruiker kan het herstellen. BBB 2.6+
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 CSS injection 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 — JSON-array met de sneltoetsen die ingeschakeld blijven (bijv. ["toggleMute","raiseHand"]); een lege array schakelt alle sneltoetsen uit.
userdata-enable-user-reaction Removed in 4.0 Boolean — Wordt door de client gelezen, maar bbb-web verwijdert elke userdata--parameter waarvan de sleutel een koppelteken bevat. Daardoor bereikt deze parameter de client nooit en heeft deze geen effect. Gebruik in plaats daarvan de waarde userReactions van disabledFeatures.

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.

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. In breakoutrooms is de blokkeerlijst ook van toepassing op moderators. 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.

In BigBlueButton 3.0 staan de parameters die door de client worden gelezen in de beheerdershandleiding (Customize, sectie "Passing user metadata to the client on join"). De broncode van de client (aanroepen van getFromUserSettings in de HTML5-client) is de gezaghebbende referentie.