userdata – Client-Einstellungen
Mit Userdata-Parametern können Sie clientseitige Einstellungen pro Benutzer überschreiben, indem Sie der API-Anfrage userdata- Parameter mit dem Präfix join anhängen. Dadurch können Sie das BigBlueButton-Erlebnis für einzelne Teilnehmer anpassen, ohne die Serverkonfiguration zu ändern.
Seit BigBlueButton 4.0 enthält die offizielle API-Referenz eine vollständige Tabelle der userdata-bbb_*-Parameter. Die unten als undokumentiert gekennzeichneten Parameter wurden aus einer Quellcodeanalyse abgeleitet und können sich ohne Vorankündigung ändern.
Wie Userdata-Parameter funktionieren
Userdata-Parameter werden als URL-Query-Parameter in der Anfrage join übergeben. Sie überschreiben die Standardwerte aus settings.yml nur für diese einzelne Benutzersitzung. Die Parameternamen beginnen immer mit dem Präfix userdata-, gefolgt vom Einstellungsschlüssel.
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 Da Userdata-Parameter Teil des Query-Strings sind, werden sie in die Berechnung von checksum einbezogen. Stellen Sie sicher, dass Sie sie vor der Berechnung von checksum hinzufügen, nicht danach.
Der Teil nach userdata- darf keinen weiteren Bindestrich enthalten – andernfalls wird der Parameter verworfen. Das Präfix userdata-bbb_ ist für BigBlueButton reserviert; Integrationen, die eigene benutzerspezifische Daten anhängen, sollten ein eigenes Präfix verwenden, zum Beispiel userdata-myapp_cohort=2026A. Solche Parameter werden mit dem Benutzer gespeichert und in die Aufzeichnungsereignisse geschrieben, vom Client jedoch ignoriert.
Audio- und Medienparameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_auto_join_audio | Boolean | — | Dem Audiobridge automatisch beitreten, wenn der Benutzer das Meeting betritt. |
userdata-bbb_listen_only_mode | Boolean | — | listen-only-Modus für den Benutzer aktivieren oder deaktivieren. Wird nur ausgewertet, wenn das Meeting audioBridge=bbb-webrtc-sfu verwendet. Bei der standardmäßigen livekit-Bridge treten Benutzer über eine stummgeschaltete Mikrofonverbindung bei, statt einen separaten Nur-Zuhören-Modus zu verwenden. |
userdata-bbb_force_listen_only | Boolean | — | Den Benutzer in den listen-only-Modus zwingen. Dies gilt nicht für Moderatoren. |
userdata-bbb_skip_check_audio | Boolean | — | Den Audiotest-Dialog beim Beitritt überspringen. |
userdata-bbb_skip_echotest_if_previous_device | Boolean | — | Den Echo-Test überspringen, wenn dasselbe Audiogerät wie in der vorherigen Sitzung erkannt wird. |
Webcam-Parameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_auto_share_webcam | Boolean | — | Die Webcam-Freigabe automatisch starten, wenn der Benutzer beitritt. |
userdata-bbb_mirror_own_webcam | Boolean | — | Die eigene Webcam-Vorschau des Benutzers horizontal spiegeln. |
Layout- und Anzeigeparameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_default_layout | String | — | Layout, mit dem der Client startet. enforceLayout bei join hat Vorrang; ist keines von beiden festgelegt, wird das Meeting-Layout verwendet. Mögliche Werte: UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY. BBB 3.0+ |
userdata-bbb_hide_presentation_on_join | Boolean | false | Mit minimiertem Präsentationsbereich starten; der Benutzer kann ihn wiederherstellen. BBB 2.6+ |
userdata-bbb_hide_sidebar_navigation | Boolean | false | Die Navigationsspalte und den Inhaltsbereich der Seitenleiste schließen, wenn der Benutzer beitritt. BBB 4.0+ |
userdata-bbb_prefer_dark_theme | Boolean | — | Das dunkle Design für die Benutzeroberfläche aktivieren. true startet im dunklen Modus, false im hellen Modus; hat Vorrang vor der Einstellung des Betriebssystems. |
Anpassungs- und Branding-Parameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_custom_style | String | — | Inline-CSS-Regeln (URL-kodiert), die für diesen Benutzer auf den BigBlueButton-Client angewendet werden. |
userdata-bbb_custom_style_url | URL | — | URL zu einer externen CSS-Datei, die vom Client für benutzerdefiniertes Styling geladen wird. Muss über HTTPS bereitgestellt werden. |
Der Parameter userdata-bbb_custom_style kann für CSS injection ausgenutzt werden, wenn join-URLs clientseitig erstellt werden. Generieren Sie join-URLs immer auf dem Server, wo Sie die Parameterwerte kontrollieren.
Parameter für UI-Elemente
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_hide_notifications | Boolean | — | Benachrichtigungs-Pop-ups in der Client-Oberfläche ausblenden. |
userdata-bbb_hide_controls | Boolean | — | Die UI-Steuerelemente (Toolbar-Schaltflächen) für den Benutzer ausblenden. |
userdata-bbb_shortcuts | String | — | JSON-Array der Tastenkombinationen, die aktiviert bleiben (z. B. ["toggleMute","raiseHand"]); ein leeres Array deaktiviert alle Tastenkombinationen. |
Whiteboard-Parameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
userdata-bbb_initial_selected_tool | String | — | Legt das anfänglich ausgewählte Whiteboard-Werkzeug fest, wenn der Benutzer das Whiteboard öffnet. Die akzeptierten Werte werden durch die Client-Konfiguration bestimmt. |
Praktische Beispiele
Nachfolgend finden Sie gängige Kombinationen von Userdata-Parametern für typische Anwendungsfälle.
Kiosk-Modus
Ideal für Bildschirme in Konferenzräumen oder digitale Beschilderung, bei denen keine Benutzerinteraktion erforderlich ist:
userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true Mandantenspezifisches Branding
Ein benutzerdefiniertes CSS-Stylesheet pro Mandant oder Kunde anwenden:
userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css Barrierefreier Schnellbeitritt
Vereinfachen Sie den Beitrittsprozess für Benutzer, die eine vereinfachte, barrierefreie Nutzung benötigen:
userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true Wichtige Hinweise
- Userdata-Parameter wirken sich nur auf die aktuelle Sitzung des einzelnen Benutzers aus. Sie ändern nicht die Server-Standardeinstellungen.
- Nicht alle Parameter sind in jeder BigBlueButton-Version verfügbar. Testen Sie gegen Ihre Zielversion, bevor Sie die Bereitstellung vornehmen.
- CSS, geladen über
userdata-bbb_custom_style_url, muss über HTTPS bereitgestellt werden.
Bei Verwendung des Endpunkts getJoinUrl werden bestimmte Userdata-Parameter für Zuschauer (Rolle VIEWER) als Sicherheitsmaßnahme blockiert. Die Sperrliste wird serverseitig über die Eigenschaft getJoinUrlUserdataBlocklist in bigbluebutton.properties konfiguriert. Dies verhindert, dass Zuschauer sicherheitskritische Client-Einstellungen über vorab signierte join-URLs überschreiben. In Breakout-Räumen gilt die Sperrliste auch für Moderatoren.
Häufig gestellte Fragen
userdata-bbb_force_listen_only gilt nur für Zuschauer. Moderatoren werden unabhängig von dieser Einstellung nicht in den listen-only-Modus gezwungen.userdata-bbb_*-Parameter im Abschnitt „User metadata parameters“ auf.