Wersja API: 4.x najnowsza 3.x

Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.

Rozdział 19

userdata – Ustawienia klienta

Parametry userdata pozwalają nadpisywać ustawienia po stronie klienta dla każdego użytkownika osobno poprzez dodanie parametrów z prefiksem userdata- do wywołania API join. Pozwala to dostosować środowisko BigBlueButton dla poszczególnych uczestników bez zmiany konfiguracji serwera.

W BigBlueButton 3.0 parametry userdata nie są wymienione w dokumentacji API, lecz w podręczniku administratora (Customize, sekcja „Passing user metadata to the client on join”). Parametry mogą się zmieniać między wersjami bez powiadomienia.

Jak działają parametry userdata

Parametry userdata są przekazywane jako parametry zapytania URL w żądaniu join. Nadpisują domyślne wartości z settings.yml tylko dla tej pojedynczej sesji użytkownika. Nazwy parametrów zawsze zaczynają się od prefiksu userdata-, po którym następuje klucz ustawienia.

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

Ponieważ parametry userdata są częścią ciągu zapytania, są uwzględniane przy obliczaniu checksum. Upewnij się, że dodasz je przed obliczeniem checksum, a nie po.

Część po userdata- nie może zawierać kolejnego łącznika — w przeciwnym razie parametr zostanie pominięty. Prefiks userdata-bbb_ jest zarezerwowany dla BigBlueButton; integracje dołączające własne dane poszczególnych użytkowników powinny używać własnego prefiksu, na przykład userdata-myapp_cohort=2026A. Takie parametry są przechowywane wraz z danymi użytkownika i zapisywane w zdarzeniach nagrania, ale klient je ignoruje.

Parametry audio i mediów

Parametr Typ Domyślnie Opis
userdata-bbb_auto_join_audio Boolean — Automatycznie dołącz do mostka audio, gdy użytkownik wejdzie na spotkanie.
userdata-bbb_listen_only_mode Boolean — Włącz lub wyłącz tryb listen-only dla użytkownika.
userdata-bbb_force_listen_only Boolean — Wymuś dla użytkownika tryb listen-only. Nie dotyczy to moderatorów.
userdata-bbb_skip_check_audio Boolean — Pomiń okno dialogowe testu audio podczas dołączania.
userdata-bbb_skip_echotest_if_previous_device Boolean — Pomiń test echa, jeśli zostanie wykryte to samo urządzenie audio co w poprzedniej sesji.

Parametry kamery internetowej

Parametr Typ Domyślnie Opis
userdata-bbb_auto_share_webcam Boolean — Automatycznie rozpocznij udostępnianie kamery internetowej, gdy użytkownik dołączy.
userdata-bbb_mirror_own_webcam Boolean — Odbij poziomo podgląd własnej kamery użytkownika.

Parametry układu i wyświetlania

Parametr Typ Domyślnie Opis
userdata-bbb_default_layout String — Układ, w którym uruchamia się klient. Parametr enforceLayout w join ma pierwszeństwo; jeśli nie podano żadnego z nich, używany jest układ spotkania. Akceptuje te same wartości co meetingLayout w create. BBB 3.0+
userdata-bbb_change_layout Removed in 4.0 String — Starszy przełącznik układu. Akceptuje te same wartości co meetingLayout w create (na przykład SMART_LAYOUT) i ma pierwszeństwo przed userdata-bbb_default_layout. Zamiast niego użyj userdata-bbb_default_layout.
userdata-bbb_hide_presentation_on_join Boolean false Uruchom z zminimalizowanym obszarem prezentacji; użytkownik może go przywrócić. BBB 2.6+
userdata-bbb_prefer_dark_theme Boolean — Włącz ciemny motyw interfejsu użytkownika.

Parametry dostosowania i brandingu

Parametr Typ Domyślnie Opis
userdata-bbb_custom_style String — Reguły CSS inline (zakodowane w URL) stosowane do klienta BigBlueButton dla tego użytkownika.
userdata-bbb_custom_style_url URL — URL do zewnętrznego pliku CSS ładowanego przez klienta dla niestandardowego stylowania. Musi być serwowany przez HTTPS.

Parametr userdata-bbb_custom_style może zostać wykorzystany do CSS injection, jeśli URL-e join są konstruowane po stronie klienta. Zawsze generuj URL-e join na serwerze, gdzie kontrolujesz wartości parametrów.

Parametry elementów interfejsu użytkownika

Parametr Typ Domyślnie Opis
userdata-bbb_hide_notifications Boolean — Ukryj wyskakujące powiadomienia w interfejsie klienta.
userdata-bbb_hide_controls Boolean — Ukryj elementy sterujące interfejsu użytkownika (przyciski paska narzędzi) przed użytkownikiem.
userdata-bbb_shortcuts String — Tablica JSON skrótów klawiszowych, które pozostają włączone (np. ["toggleMute","raiseHand"]); pusta tablica wyłącza wszystkie skróty.
userdata-enable-user-reaction Removed in 4.0 Boolean — Odczytywany przez klienta, ale bbb-web odrzuca każdy parametr userdata-, którego klucz zawiera łącznik, więc ten parametr nigdy nie dociera do klienta i nie ma żadnego efektu. Zamiast tego użyj wartości userReactions parametru disabledFeatures.

Parametry tablicy

Parametr Typ Domyślnie Opis
userdata-bbb_initial_selected_tool String — Ustaw narzędzie tablicy wybrane początkowo, gdy użytkownik otworzy tablicę. Akceptowane wartości są określane przez konfigurację klienta.

Praktyczne przykłady

Poniżej znajdują się typowe kombinacje parametrów userdata dla najczęstszych przypadków użycia.

Tryb kiosku

Idealny do ekranów w salach konferencyjnych lub oznakowania cyfrowego, gdzie nie jest wymagana żadna interakcja użytkownika:

userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true

Branding specyficzny dla tenantu

Zastosuj niestandardowy arkusz stylów CSS dla każdego tenanta lub klienta:

userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css

Dostępne szybkie dołączanie

Uprość proces dołączania dla użytkowników, którzy potrzebują prostego i dostępnego sposobu korzystania:

userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true

Ważne uwagi

  • Parametry userdata wpływają tylko na bieżącą sesję konkretnego użytkownika. Nie zmieniają domyślnych ustawień serwera.
  • Nie wszystkie parametry są dostępne w każdej wersji BigBlueButton. Przed wdrożeniem przetestuj je względem docelowej wersji.
  • CSS ładowany przez userdata-bbb_custom_style_url musi być serwowany przez HTTPS.

Podczas używania endpointu getJoinUrl niektóre parametry userdata są blokowane dla widzów (rola VIEWER) jako środek bezpieczeństwa. Lista blokowanych parametrów jest konfigurowana po stronie serwera przez właściwość getJoinUrlUserdataBlocklist w bigbluebutton.properties. Zapobiega to nadpisywaniu przez widzów krytycznych ustawień bezpieczeństwa klienta za pomocą wstępnie podpisanych URL-i join. W pokojach grupowych lista blokad dotyczy również moderatorów. undocumented

Najczęściej zadawane pytania

Nie. Parametry userdata są stosowane tylko do pojedynczej sesji zainicjowanej wywołaniem join. Jeśli użytkownik opuści spotkanie i dołączy ponownie, parametry muszą zostać ponownie uwzględnione w nowym URL-u join.

Nie. Parametry userdata są przeznaczone wyłącznie dla endpointu join. Są przetwarzane przez klienta, gdy użytkownik dołącza do spotkania, i nie mają żadnego wpływu na wywołanie create.

Tak. Ponieważ są częścią ciągu zapytania URL, są uwzględniane przy obliczaniu checksum. Musisz dodać wszystkie parametry userdata do ciągu zapytania przed obliczeniem checksum.

Nie. Parametr userdata-bbb_force_listen_only dotyczy wyłącznie widzów. Moderatorzy nie są zmuszani do trybu listen-only niezależnie od tego ustawienia.

W BigBlueButton 3.0 parametry odczytywane przez klienta są wymienione w podręczniku administratora (Customize, sekcja „Passing user metadata to the client on join”). Kod źródłowy klienta (wywołania getFromUserSettings w kliencie HTML5) jest rozstrzygającym źródłem informacji.