Capitolo 18

Meta-parametri e callback

I meta parametri sono coppie chiave-valore liberamente definibili che passi quando crei una riunione. Ti consentono di allegare metadati personalizzati, attivare callback automatici su eventi specifici, controllare l'anonimizzazione delle registrazioni e documentare l'origine di una riunione per le integrazioni LMS.

Come funzionano i parametri meta

I parametri meta vengono passati nella chiamata API create usando la convenzione di denominazione meta_=. Puoi allegare qualsiasi numero di parametri meta a una singola riunione. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • I parametri meta vengono restituiti nelle risposte getMeetingInfo e getRecordings.
  • Le registrazioni possono essere filtrate per valori meta usando getRecordings?meta_=.
  • I metadati delle registrazioni possono essere aggiornati successivamente tramite updateRecordings.

Parametri meta di callback

Alcuni meta parametri hanno un significato speciale e attivano callback HTTP quando si verificano eventi specifici. Questi consentono alla tua applicazione di reagire automaticamente agli eventi del ciclo di vita della riunione.

meta_endCallbackUrl

Attiva una richiesta HTTP GET all'URL specificato quando la riunione termina. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Proprietà Valore
Metodo HTTP GET
Attivazione Quando la riunione termina
Parametri Callback meetingID — l'identificatore della riunione
recordingmarks — true se la registrazione contiene marcatori, altrimenti false

Esempio di richiesta di callback: 

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Attiva una richiesta HTTP POST quando la registrazione è stata completamente elaborata e pubblicata. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Proprietà Valore
Metodo HTTP POST
Attivazione Quando la registrazione è completamente elaborata e pubblicata
Sicurezza I parametri sono firmati con JWT (JSON Web Token)
Body POST Contiene dati firmati con informazioni sulla registrazione

Non confondere questa callback con endCallbackUrl. L'elaborazione della registrazione può richiedere molto tempo dopo la fine della riunione. La callback recording-ready viene attivata solo una volta completata l'elaborazione.

meta_analytics-callback-url

Attiva una richiesta HTTP POST con dati analitici aggregati dopo la fine della riunione. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Proprietà Valore
Metodo HTTP POST
Attivazione Dopo la fine della riunione (post-events hook)
Autenticazione Token JWT inviato come header Authorization: Bearer (HS512, firmato con il segreto condiviso BBB, valido per 24 ore)
Formato del corpo Oggetto JSON contenente version, meeting_id, internal_meeting_id, data
Contenuto dei dati Durata della partecipazione, statistiche di attività, utilizzo della chat e altri eventi aggregati della riunione

L'URL della callback analytics proviene dal codebase BigBlueButton e non è documentato completamente nella documentazione ufficiale dell'API. Lo schema esatto dell'oggetto dei dati analitici non è standardizzato e può cambiare tra le versioni. undocumented

Nota la differenza nella consegna di JWT: analytics-callback-url invia JWT come header HTTP Authorization, mentre bbb-recording-ready-url include JWT direttamente nel body POST.

Parametri di anonimizzazione della registrazione

Questi meta parametri controllano se i nomi dei mittenti della chat vengono anonimizzati nelle registrazioni elaborate. Sono utili per la conformità alla privacy e i requisiti di protezione dei dati.

Parametro Tipo Predefinito Descrizione
meta_bbb-anonymize-chat Boolean false Anonimizza i mittenti dei messaggi della chat nelle registrazioni elaborate. Influisce solo sui messaggi dei partecipanti (non moderatori). I nomi dei moderatori rimangono visibili.
meta_bbb-anonymize-chat-moderators Boolean false Inoltre anonimizza i mittenti dei messaggi della chat dei moderatori nelle registrazioni. In genere richiede anche che sia impostato meta_bbb-anonymize-chat=true.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

I parametri di anonimizzazione sono menzionati solo brevemente nella documentazione ufficiale dell'API. Il loro comportamento è ricavato dal codice sorgente BigBlueButton. undocumented

Parametri di integrazione LMS

Molti plugin LMS impostano automaticamente meta parametri per documentare l'origine di una riunione. Questi sono informativi e non influenzano il comportamento della riunione, ma sono utili per audit e reportistica.

Parametro Esempio Descrizione
meta_bbb-origin greenlight, moodle L'applicazione di origine che ha creato la riunione.
meta_bbb-origin-version v3.1.0 Versione dell'applicazione di origine.
meta_bbb-origin-server-name api-guide.bbbserver.com Hostname dell'applicazione di origine.
meta_bbb-context Course: Computer Science Informazioni di contesto come il nome del corso.
meta_bbb-context-id course-42 Identificatore di contesto per uso programmatico.

Best practice per meta parametri personalizzati

  • Usa nomi chiave descrittivi (ad es. meta_department, meta_project) che indichino chiaramente lo scopo del valore.
  • Codifica in URL i valori che contengono caratteri speciali, spazi o caratteri non ASCII.
  • Usa i meta parametri per l'integrazione con sistemi esterni come CRMs, piattaforme di apprendimento o dashboard di analytics.
  • Aggiorna i metadati della registrazione successivamente usando l'endpoint updateRecordings per aggiungere o correggere metadati.

Combina i meta parametri con il filtro di getRecordings per creare potenti flussi di lavoro di ricerca e categorizzazione per le tue registrazioni. Ad esempio, filtra per meta_department=engineering per recuperare solo le registrazioni delle riunioni del reparto engineering.

Domande frequenti

Non esiste un limite rigido al numero di meta parametri. Tuttavia, poiché vengono passati come parametri di query URL, dovresti rimanere entro limiti pratici di lunghezza dell'URL (in genere da 2.000 a 8.000 caratteri a seconda della configurazione del server web).

I meta parametri impostati durante la chiamata create non possono essere modificati mentre la riunione è in corso. Tuttavia, i metadati della registrazione possono essere aggiornati dopo l'elaborazione usando l'endpoint updateRecordings.

endCallbackUrl viene attivato immediatamente quando la riunione termina, usando una semplice richiesta GET. bbb-recording-ready-url viene attivato molto più tardi, solo dopo che la registrazione è stata completamente elaborata e pubblicata, e usa una richiesta JWT firmata con POST.

I dettagli della firma JWT non sono specificati completamente nella documentazione ufficiale. In base al codice sorgente BigBlueButton, JWT viene firmato usando il segreto condiviso del server. Le claim esatte e l'algoritmo dovrebbero essere verificati rispetto alla tua specifica versione BigBlueButton.

La maggior parte dei meta parametri è puramente informativa e non modifica il funzionamento della riunione. Le eccezioni sono gli URL di callback, che attivano richieste HTTP sugli eventi, e i parametri di anonimizzazione, che influenzano il modo in cui le registrazioni vengono elaborate.

Sì. Le chiavi dei meta parametri sono trattate come stringhe sensibili alle maiuscole e minuscole. Per esempio, meta_Department e meta_department verrebbero memorizzati come due parametri separati. Usa una capitalizzazione coerente nella tua integrazione per evitare duplicati.