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.

Questo è l'unico endpoint API BigBlueButton che restituisce JSON invece di XML.

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-* ↗ undocumented 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>",
        "sessionToken": "replace-with-session-token"
  }
}
Messaggio Significato
Invalid Session Il sessionToken non è valido o è scaduto.
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.

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.

Note per gli utenti di bbbserver.de

L'endpoint getJoinUrl è disponibile su tutte le istanze bbbserver.de che eseguono BigBlueButton 3.0 o versioni successive. Se la tua integrazione deve supportare scenari multi-schermo o di cambio dispositivo, questo endpoint fornisce un modo pulito per generare URL di accesso aggiuntivi senza richiedere una seconda chiamata join con credenziali da moderatore.

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.

Questa è una scelta progettuale fatta dagli sviluppatori di BigBlueButton quando hanno introdotto questo endpoint nella versione 3.0. È l'unico endpoint API che restituisce JSON. Tutti gli altri endpoint continuano a restituire 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.