Kapitel 19

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.

Die Liste der verfügbaren Userdata-Parameter wird in der offiziellen BigBlueButton-Dokumentation nur teilweise behandelt. Viele Parameter ergeben sich aus Quellcodeanalysen von settings.yml und können sich zwischen Versionen ohne Ankündigung ändern. undocumented

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.

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.
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_auto_swap_layout Boolean — Das Layout automatisch wechseln, wenn eine Präsentation freigegeben wird.
userdata-bbb_default_layout String — Das Standardlayout für den Benutzer festlegen. Die verfügbaren Werte hängen von der Client-Konfiguration ab. undocumented
userdata-bbb_hide_presentation Boolean — Den Präsentationsbereich für den Benutzer ausblenden.
userdata-bbb_prefer_dark_theme Boolean — Das dunkle Design für die Benutzeroberfläche aktivieren.

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 cross-site scripting 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 — Benutzerdefinierte Tastenkombinationen für den Benutzer festlegen.

Parameter für Aufzeichnung und externe Steuerung

Parameter Typ Standard Beschreibung
userdata-bbb_outside_toggle_recording Boolean — Einer externen Anwendung erlauben, die Meeting-Aufzeichnung ein- und auszuschalten.
userdata-bbb_outside_toggle_self_voice Boolean — Einer externen Anwendung erlauben, den Ton des Benutzers ein- und auszuschalten.

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. undocumented

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. undocumented

Häufig gestellte Fragen

Nein. Userdata-Parameter werden nur auf die einzelne Sitzung angewendet, die durch den Aufruf join gestartet wird. Wenn der Benutzer geht und erneut beitritt, müssen die Parameter erneut in die neue join-URL aufgenommen werden.

Nein. Userdata-Parameter sind nur für den Endpunkt join vorgesehen. Sie werden vom Client verarbeitet, wenn ein Benutzer einem Meeting beitritt, und haben keine Auswirkung auf den Aufruf create.

Ja. Da sie Teil des URL-Query-Strings sind, werden sie in die Berechnung von checksum einbezogen. Sie müssen alle Userdata-Parameter zum Query-String hinzufügen, bevor Sie checksum berechnen.

Nein. Der Parameter userdata-bbb_force_listen_only gilt nur für Zuschauer. Moderatoren werden unabhängig von dieser Einstellung nicht in den listen-only-Modus gezwungen.

Die offizielle Dokumentation deckt nur einen Teilbereich ab. Die vollständigste und aktuellste Liste befindet sich in der Datei settings.yml innerhalb des Quellcodes des BigBlueButton-Clients. Neue Parameter werden häufig hinzugefügt, ohne dass die Dokumentation aktualisiert wird.