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ł 4 GET

join – Dołącz do spotkania

Punkt końcowy join generuje URL, który umożliwia użytkownikowi wejście do trwającego spotkania BigBlueButton. Domyślnie przeglądarka jest bezpośrednio przekierowywana do klienta BBB. Gdy redirect jest ustawione na false, zamiast tego zwracana jest odpowiedź XML zawierająca URL dołączenia i token sesji.

Punkt końcowy

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum

Wywołanie join jest jedynym punktem końcowym API chronionym sumą kontrolną, który jest wywoływany bezpośrednio w przeglądarce użytkownika końcowego (jako adres URL przekierowania). Wszystkie pozostałe wywołania API chronione sumą kontrolną są wykonywane po stronie serwera.

Wymagane parametry

Parametr Typ Opis
meetingID String Wymagane. Identyfikator spotkania, do którego należy dołączyć.
fullName String Wymagane. Wyświetlana nazwa użytkownika na spotkaniu.
role Enum Wymagane. Rola użytkownika: MODERATOR lub VIEWER (bez rozróżniania wielkości liter). BBB 2.4+

Parametry przestarzałe

Parametr Typ Opis
password String Przestarzałe Przestarzałe od BBB 3.0. Przypisywanie ról przez hasło (attendeePW/moderatorPW z create). Zastąpione przez role.
webVoiceConf String Przestarzałe Removed in 4.0 Niestandardowy numer wewnętrzny połączenia głosowego dla starego klienta Flash. Wartość nie jest przetwarzana i nie ma żadnego efektu.

Parametry opcjonalne

Parametr Typ Domyślnie Opis
createTime Number (Long) — Znacznik czasu z odpowiedzi create. Zapobiega dołączeniu do spotkania, które zostało utworzone ponownie po wygenerowaniu adresu URL dołączenia.
userID String — Specyficzny dla aplikacji identyfikator użytkownika. Zwracany w getMeetingInfo i webhooks.
avatarURL String — Adres URL obrazu awatara użytkownika.
webcamBackgroundURL String — Adres URL niestandardowego obrazu tła kamery internetowej.
firstName String — Imię (używane do sortowania, nie do wyświetlania).
lastName String — Nazwisko (używane do sortowania, nie do wyświetlania).
redirect Boolean true Gdy ustawione na false, zamiast przekierowania przeglądarki zwracana jest odpowiedź XML.
errorRedirectUrl String — Alternatywny adres URL, na który nastąpi przekierowanie w przypadku błędów (zamiast domyślnej strony błędu).
logoutURL String — Adres URL, na który nastąpi przekierowanie po wylogowaniu. Zastępuje wartość z create.
guest Boolean false Oznacz użytkownika jako gościa. Podlega zasadzie guestPolicy spotkania.
bot Boolean false Oznacz użytkownika jako zautomatyzowanego agenta.
excludeFromDashboard Boolean false Wyklucz użytkownika z panelu analityki uczenia się.
enforceLayout Enum — Wymuś określony układ dla tego użytkownika. Możliwe wartości: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
auth Boolean (warunkowe) ‎⚠ Nieudokumentowane Oznacz użytkownika jako uwierzytelnionego. Logika warunkowa: jeśli nie podano guest, domyślną wartością auth jest true. Jeśli podano guest (z dowolną wartością, w tym false), domyślną wartością auth jest false, chyba że ustawiono ją jawnie.
defaultLayout String — ‎⚠ Nieudokumentowane Usunięty z oficjalnego API w BBB 3.0. Serwer nadal akceptuje tę wartość, ale nigdy jej nie przetwarza, więc nie ma ona żadnego efektu. Użyj userdata-bbb_default_layout, aby ustawić układ, w którym uruchamia się klient.
sessionName String — ‎⚠ Nieudokumentowane Niestandardowa nazwa sesji. Działa tylko w połączeniu z existingUserID.
existingUserID String — ‎⚠ Nieudokumentowane Wewnętrzny identyfikator użytkownika do ponownego dołączenia lub ponownego połączenia z istniejącą sesją.
replaceSessionToken String — ‎⚠ Nieudokumentowane Token sesji do zastąpienia (gdy jest używany z existingUserID).

Parametry Userdata

Podczas wywoływania join możesz przekazywać niestandardowe dane jako parametry userdata-=. Są one udostępniane w kliencie i mogą sterować zachowaniem wtyczek lub ustawieniami klienta dla poszczególnych użytkowników.

Lista blokad getJoinUrlUserdataBlocklist po stronie serwera dotyczy tylko adresów URL dołączania generowanych przez getJoinUrl. Samo wywołanie join akceptuje wszystkie klucze userdata.

Część po userdata- nie może zawierać kolejnego łącznika, w przeciwnym razie parametr zostanie odrzucony. Prefiks userdata-bbb_ jest zarezerwowany dla BigBlueButton – użyj własnego prefiksu dla danych integracji (np. userdata-myapp_cohort). Pełna lista jest dostępna w rozdziale Ustawienia klienta.

Przykładowe żądanie

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum

Przykładowa odpowiedź (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
  <meeting_id>replace-with-internal-meeting-id</meeting_id>
  <user_id>replace-with-user-id</user_id>
  <auth_token>replace-with-auth-token</auth_token>
  <session_token>replace-with-session-token</session_token>
  <guestStatus>ALLOW</guestStatus>
  <url>https://api-guide.bbbserver.com/html5client/?sessionToken=replace-with-session-token</url>
</response>

Odpowiedzi błędów

messageKey Znaczenie
invalidMeetingIdentifier Spotkanie nie istnieje.
meetingForciblyEnded Spotkanie zostało wymuszenie zakończone.
maxParticipantsReached Osiągnięto limit uczestników.
guestDeniedAccess Gościowi odmówiono dostępu.
invalidPassword Hasło jest nieprawidłowe.
checksumError checksum jest nieprawidłowy.
mismatchCreateTimeParam Parametr createTime nie pasuje do spotkania.
userNotFound Nie znaleziono aktywnego użytkownika z tym ID (przy użyciu existingUserID).

Używanie createTime do walidacji URL dołączenia

Parametr createTime służy jako zabezpieczenie przed nieaktualnymi URL-ami dołączania:

Spotkanie zostaje utworzone i zwraca createTime: 1715261728123.

URL dołączania jest generowany z createTime=1715261728123.

Spotkanie kończy się i zostaje utworzone ponownie z nowym createTime.

Stary URL dołączania z poprzednim createTime zostaje odrzucony.

Zapobiega to wejściu użytkowników z nieaktualnymi linkami zaproszeń do nowego spotkania, które używa tego samego meetingID.

Na bbbserver.de uczestnicy, którzy dołączają przez pokoje lub linki z zaproszeniami w interfejsie internetowym bbbserver.de, otrzymują automatycznie wygenerowany adres URL dołączania. Jeśli korzystasz z Integration API, samodzielnie utwórz wywołanie join zgodnie z powyższym opisem.

Wskazówki bezpieczeństwa

Nigdy nie ujawniaj shared secret po stronie klienta w celu obliczania URL-i dołączania. Zawsze generuj URL-e dołączania po stronie serwera i przekazuj je klientowi.

  • Wygenerowany URL dołączania zawiera checksum i powinien być użyty tylko raz.
  • URL-e dołączania powinny być generowane po stronie serwera i przekazywane klientowi.
  • W przypadku wrażliwych spotkań użyj guest=true razem z guestPolicy=ASK_MODERATOR.

Przejście z password na role to jedna z najistotniejszych zmian łamiących kompatybilność w BBB 3.0. Upewnij się, że odpowiednio zaktualizujesz swoją integrację.

Najczęściej zadawane pytania

W BBB 3.0 i nowszych parametr role (MODERATOR lub VIEWER) zastępuje przypisywanie ról oparte na haśle używane we wcześniejszych wersjach. Parametr password jest przestarzały i nie powinien być już używany w nowych integracjach.

Zamiast przekierowywać przeglądarkę do spotkania, serwer zwraca odpowiedź XML zawierającą URL dołączenia i token sesji. Jest to przydatne w integracjach po stronie serwera, które muszą sprawdzić odpowiedź lub programowo zarządzać tokenem sesji.

Tak. Użyj parametru existingUserID z wewnętrznym identyfikatorem użytkownika z poprzedniej sesji, aby ponownie się połączyć. Możesz również przekazać replaceSessionToken, aby zastąpić starą sesję. Pamiętaj, że te parametry nie są udokumentowane i mogą ulec zmianie bez powiadomienia.

Gdy guest jest ustawione na true, użytkownik jest oznaczany jako gość i podlega zasadzie guestPolicy zdefiniowanej podczas tworzenia spotkania. Na przykład przy ASK_MODERATOR moderator musi zatwierdzić gościa, zanim będzie mógł wejść.

Parametry Userdata (userdata-=) pozwalają przekazywać niestandardowe dane do klienta spotkania dla poszczególnych użytkowników. Mogą być używane do konfigurowania zachowania klienta, przekazywania informacji do wtyczek lub dostosowywania doświadczenia użytkownika.

Ten błąd występuje, gdy wartość createTime w URL dołączania nie odpowiada wartości createTime aktualnie uruchomionego spotkania. Zwykle dzieje się tak, gdy spotkanie zostało zakończone i utworzone ponownie z tym samym meetingID, ale URL dołączania nadal zawiera stare createTime.