Versione API: 4.x più recente 3.x

Stai visualizzando la documentazione API per BigBlueButton 3.x. La versione attuale è BigBlueButton 4.x. Stai pianificando un aggiornamento? La guida alla migrazione elenca tutte le modifiche necessarie alle tue chiamate API.

Capitolo 7 GET POST

getJoinUrl – Genera URL di accesso

L'endpoint getJoinUrl genera un nuovo URL di accesso per un utente che è già entrato in una riunione. Ciò consente allo stesso utente di aprire sessioni aggiuntive — ad esempio su un secondo schermo o dopo aver cambiato dispositivo — senza riautenticarsi tramite il normale flusso join. BBB 3.0+

Endpoint

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

Questo endpoint usa l'session-token autenticazione invece del meccanismo standard di shared-secret checksum. L'utente deve essere già entrato tramite l'endpoint join e possedere un sessionToken valido.

A differenza degli endpoint API BigBlueButton protetti da checksum, che restituiscono XML, questo endpoint restituisce JSON.

Parametri obbligatori

Parametro Tipo Obbligatorio Predefinito Descrizione
sessionToken String Sì — Il sessionToken dell'utente per cui deve essere generato un nuovo URL di accesso.

Parametri opzionali

Parametro Tipo Obbligatorio Predefinito Descrizione
replaceSession Boolean No false Se impostato su true, la sessione originale viene invalidata e sostituita da quella nuova (trasferimento di sessione).
sessionName String No — Un nome descrittivo per la nuova sessione.
enforceLayout String No — Sovrascrivi il layout per la nuova sessione.
userdata-* String No — Dati utente personalizzati per la nuova sessione. Le chiavi devono avere il prefisso userdata-.

Casi d’uso

  • Scenari ibridi — un moderatore usa uno schermo per la presentazione e un secondo schermo per la vista partecipante.
  • Cambio di dispositivo — un utente passa dal desktop a un tablet durante una riunione.
  • Configurazioni multi-schermo — una sala conferenze con più display che mostrano layout differenti.

Comportamento

La nuova sessione condivide l'identità utente con la sessione originale. L'utente appare una sola volta nell'elenco dei partecipanti.

Senza replaceSession, entrambe le sessioni esistono in parallelo.

Con replaceSession=true, la sessione originale viene invalidata e l'utente viene trasferito senza interruzioni alla nuova sessione.

Esempio di richiesta

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

Esempio di risposta (successo)

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

Risposte di errore

Quando una richiesta fallisce, l'endpoint restituisce un oggetto JSON con un messaggio di errore descrittivo:

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>"
  }
}
Messaggio Significato
You must provide a session token Manca il parametro sessionToken.
Invalid session token Il sessionToken non è valido o è scaduto.
Invalid Session La richiesta non include il cookie di sessione HTTP creato da join e la riunione non consente richieste senza una sessione (allowRequestsWithoutSession, valore predefinito false).
Access denied L'utente non è stato trovato oppure non dispone dei permessi necessari.
Meeting not found La riunione non esiste o non è più in corso.

In BigBlueButton 3.0, solo Meeting not found viene restituito come errore JSON. Per gli altri errori elencati sopra, l'endpoint non invia alcuna risposta JSON.

Blocklist Userdata

Quando si usano parametri userdata-* con getJoinUrl, una blocklist configurabile (getJoinUrlUserdataBlocklist) limita determinate chiavi userdata per gli utenti non moderatori:

  • Se la blocklist contiene il valore "all", tutti i parametri userdata sono bloccati per i visualizzatori.
  • I moderatori ignorano la blocklist, tranne in breakout rooms.
  • Il parametro enforceLayout è sempre consentito, indipendentemente dalla blocklist.

L'endpoint è disponibile solo quando l'utente possiede già un sessionToken valido — cioè deve prima essere entrato nella riunione tramite il normale endpoint join. I token scaduti vengono rifiutati.

Per i casi d'uso di cambio dispositivo, imposta replaceSession=true per trasferire senza interruzioni la sessione al nuovo dispositivo. Questo evita di avere una sessione obsoleta sul vecchio dispositivo che potrebbe causare confusione nell'elenco dei partecipanti.

Domande frequenti

No. A differenza della maggior parte degli endpoint API BigBlueButton, getJoinUrl usa l'autenticazione session-token. Passi il parametro sessionToken invece di calcolare un checksum con il segreto condiviso.

No. L'utente deve essere già entrato tramite l'endpoint standard join e possedere un sessionToken valido e attivo. L'endpoint non può essere usato per creare URL di accesso iniziali.

Entrambe le sessioni — quella originale e quella nuova — esisteranno in parallelo. L'utente appare una sola volta nell'elenco dei partecipanti, ma entrambe le finestre del browser o i dispositivi rimangono attivi.

Come gli altri endpoint basati su token di sessione utilizzati internamente dal client (stuns, learningDashboard), getJoinUrl restituisce JSON. Gli endpoint API protetti da checksum restituiscono XML.

L'endpoint getJoinUrl è stato introdotto in BigBlueButton 3.0. Non è disponibile nelle versioni precedenti.

Non necessariamente. Una blocklist configurabile può limitare determinate chiavi userdata per gli utenti non moderatori. Se la blocklist è impostata su "all", nessun parametro userdata viene trasmesso ai visualizzatori. I moderatori ignorano la blocklist tranne che in breakout rooms.