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 wywoływanym bezpośrednio w przeglądarce użytkownika końcowego (jako URL przekierowania). Wszystkie pozostałe wywołania API 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 3.0+

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.

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.
‎⚠ Nieudokumentowane Oficjalna dokumentacja błędnie podaje tę wartość jako PARTICIPANTS_CHAT_ONLY (bez _AND_).
auth Boolean (warunkowe) ‎⚠ Nieudokumentowane Oznacz użytkownika jako uwierzytelnionego. Logika warunkowa: jeśli guest nie jest określone, auth domyślnie ma wartość true. Jeśli określono guest=true, auth domyślnie ma wartość false, chyba że zostanie ustawione jawnie.
defaultLayout String — ‎⚠ Nieudokumentowane Domyślny układ dla tego użytkownika. Te same wartości co meetingLayout w wywołaniu create.
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.

Niektóre klucze userdata mogą być blokowane po stronie serwera za pomocą listy blokad (getJoinUrlUserdataBlocklist).

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>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?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.

W bbbserver.de URL dołączenia jest zawsze generowany po stronie serwera z poprawnym checksum i parametrami. Nie musisz ręcznie konstruować URL-i dołączania.

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.