API-Version: 4.x neueste 3.x

Sie sehen die API-Dokumentation für BigBlueButton 3.x. Die aktuelle Version ist BigBlueButton 4.x. Planen Sie ein Upgrade? Der Migrationsleitfaden listet alle erforderlichen Änderungen an Ihren API-Aufrufen auf.

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.

In BigBlueButton 3.0 sind die userdata-Parameter nicht in der API-Referenz, sondern im Administrationshandbuch aufgeführt (Customize, Abschnitt „Passing user metadata to the client on join“). Die Parameter können sich zwischen Versionen 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.
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. Akzeptiert dieselben Werte wie meetingLayout bei create. BBB 3.0+
userdata-bbb_change_layout Removed in 4.0 String — Veralteter Layout-Schalter. Akzeptiert dieselben Werte wie meetingLayout bei create (zum Beispiel SMART_LAYOUT) und hat Vorrang vor userdata-bbb_default_layout. Verwenden Sie stattdessen userdata-bbb_default_layout.
userdata-bbb_hide_presentation_on_join Boolean false Mit minimiertem Präsentationsbereich starten; der Benutzer kann ihn wiederherstellen. BBB 2.6+
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 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.
userdata-enable-user-reaction Removed in 4.0 Boolean — Wird vom Client gelesen, aber bbb-web verwirft jeden userdata--Parameter, dessen Schlüssel einen Bindestrich enthält. Daher erreicht dieser Parameter den Client nie und hat keine Wirkung. Verwenden Sie stattdessen den Wert userReactions von disabledFeatures.

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

In BigBlueButton 3.0 sind die vom Client gelesenen Parameter im Administrationshandbuch aufgeführt (Customize, Abschnitt „Passing user metadata to the client on join“). Der Quellcode des Clients (Aufrufe von getFromUserSettings im HTML5-Client) ist die maßgebliche Referenz.