Kapitel 7 GET POST

getJoinUrl – Beitritts-URL generieren

Der Endpunkt getJoinUrl erzeugt eine neue Join-URL für einen Benutzer, der bereits einem Meeting beigetreten ist. Dadurch kann derselbe Benutzer zusätzliche Sitzungen öffnen — zum Beispiel auf einem zweiten Bildschirm oder nach einem Gerätewechsel — ohne sich erneut über den normalen Ablauf von join authentifizieren zu müssen. BBB 3.0+

Endpunkt

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

Dieser Endpunkt verwendet session-token-Authentifizierung anstelle des standardmäßigen shared-secret-Prüfsummenmechanismus. Der Benutzer muss bereits über den Endpunkt join beigetreten sein und ein gültiges sessionToken besitzen.

Dies ist der einzige BigBlueButton-API-Endpunkt, der JSON anstelle von XML zurückgibt.

Erforderliche Parameter

Parameter Typ Erforderlich Standard Beschreibung
sessionToken String Ja — Das sessionToken des Benutzers, für den eine neue Join-URL erzeugt werden soll.

Optionale Parameter

Parameter Typ Erforderlich Standard Beschreibung
replaceSession Boolean Nein false Wenn auf true gesetzt, wird die ursprüngliche Sitzung ungültig gemacht und durch die neue ersetzt (Sitzungsübertragung).
sessionName String Nein — Ein beschreibender Name für die neue Sitzung.
enforceLayout String Nein — Das Layout für die neue Sitzung überschreiben.
userdata-* ↗ undocumented String Nein — Benutzerdefinierte Nutzerdaten für die neue Sitzung. Schlüssel müssen mit userdata- beginnen.

Anwendungsfälle

  • Hybride Szenarien — ein Moderator verwendet einen Bildschirm für die Präsentation und einen zweiten Bildschirm für die Teilnehmeransicht.
  • Gerätewechsel — ein Benutzer wechselt während eines Meetings von seinem Desktop zu einem Tablet.
  • Mehrbildschirm-Setups — ein Konferenzraum mit mehreren Displays, die unterschiedliche Layouts anzeigen.

Verhalten

Die neue Sitzung teilt die Benutzeridentität mit der ursprünglichen Sitzung. Der Benutzer erscheint nur einmal in der Teilnehmerliste.

Ohne replaceSession existieren beide Sitzungen parallel.

Mit replaceSession=true wird die ursprüngliche Sitzung ungültig gemacht und der Benutzer nahtlos in die neue Sitzung übertragen.

Beispielanfrage

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Beispielantwort (Erfolg)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
        "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Fehlerantworten

Wenn eine Anfrage fehlschlägt, gibt der Endpunkt ein JSON-Objekt mit einer beschreibenden Fehlermeldung zurück: 

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>",
        "sessionToken": "replace-with-session-token"
  }
}
Nachricht Bedeutung
Invalid Session Das sessionToken ist ungültig oder abgelaufen.
Access denied Der Benutzer wurde nicht gefunden oder hat keine Berechtigung.
Meeting not found Das Meeting existiert nicht oder läuft nicht mehr.

Userdata Blockliste

Bei der Verwendung von userdata-*-Parametern mit getJoinUrl schränkt eine konfigurierbare Blockliste (getJoinUrlUserdataBlocklist) bestimmte userdata-Schlüssel für Nicht-Moderator-Benutzer ein:

  • Wenn die Blockliste den Wert "all" enthält, werden alle userdata-Parameter für Zuschauer blockiert.
  • Moderatoren umgehen die Blockliste, ausgenommen in breakout rooms.
  • Der Parameter enforceLayout ist unabhängig von der Blockliste immer erlaubt.

Der Endpunkt ist nur verfügbar, wenn der Benutzer bereits ein gültiges sessionToken besitzt — das heißt, er muss dem Meeting zuerst über den normalen Endpunkt join beigetreten sein. Abgelaufene Tokens werden abgelehnt.

Hinweise für bbbserver.de-Benutzer

Der Endpunkt getJoinUrl ist auf allen bbbserver.de-Instanzen verfügbar, auf denen BigBlueButton 3.0 oder höher läuft. Wenn Ihre Integration Multi-Screen- oder Gerätewechsel-Szenarien unterstützen muss, bietet dieser Endpunkt eine saubere Möglichkeit, zusätzliche Join-URLs zu erzeugen, ohne einen zweiten join-Aufruf mit Moderator-Zugangsdaten zu benötigen.

Für Gerätewechsel-Anwendungsfälle setzen Sie replaceSession=true, um die Sitzung nahtlos auf das neue Gerät zu übertragen. Dadurch wird vermieden, dass auf dem alten Gerät eine veraltete Sitzung bestehen bleibt, die in der Teilnehmerliste für Verwirrung sorgen könnte.

Häufig gestellte Fragen

Nein. Anders als die meisten BigBlueButton-API-Endpunkte verwendet getJoinUrl session-token-Authentifizierung. Sie übergeben den Parameter sessionToken, anstatt eine Prüfsumme mit dem Shared Secret zu berechnen.

Nein. Der Benutzer muss bereits über den normalen Endpunkt join beigetreten sein und ein gültiges, aktives sessionToken besitzen. Der Endpunkt kann nicht verwendet werden, um initiale Join-URLs zu erzeugen.

Beide Sitzungen — die ursprüngliche und die neue — existieren parallel. Der Benutzer erscheint nur einmal in der Teilnehmerliste, aber beide Browserfenster oder Geräte bleiben aktiv.

Dies ist eine Designentscheidung der BigBlueButton-Entwickler bei der Einführung dieses Endpunkts in Version 3.0. Es ist der einzige API-Endpunkt, der JSON zurückgibt. Alle anderen Endpunkte geben weiterhin XML zurück.

Der Endpunkt getJoinUrl wurde in BigBlueButton 3.0 eingeführt. Er ist in früheren Versionen nicht verfügbar.

Nicht unbedingt. Eine konfigurierbare Blockliste kann bestimmte userdata-Schlüssel für Nicht-Moderator-Benutzer einschränken. Wenn die Blockliste auf "all" gesetzt ist, werden für Zuschauer keine userdata-Parameter übergeben. Moderatoren umgehen die Blockliste außer in breakout rooms.