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.
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_urlmoet 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
userdata-bbb_force_listen_only geldt alleen voor kijkers. Moderators worden ongeacht deze instelling niet gedwongen in listen-only-modus.getFromUserSettings in de HTML5-client) is de gezaghebbende referentie.