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.
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_urlmusi 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
userdata-bbb_force_listen_only dotyczy wyłącznie widzów. Moderatorzy nie są zmuszani do trybu listen-only niezależnie od tego ustawienia.getFromUserSettings w kliencie HTML5) jest rozstrzygającym źródłem informacji.