Chapitre 18

Méta-paramètres et callbacks

Les métaparamètres sont des paires clé-valeur librement définissables que vous transmettez lors de la création d’une réunion. Ils vous permettent d’attacher des métadonnées personnalisées, de déclencher des callbacks automatisés lors d’événements spécifiques, de contrôler l’anonymisation des enregistrements et de documenter l’origine d’une réunion pour les intégrations LMS.

Fonctionnement des paramètres meta

Les paramètres meta sont transmis dans l’appel API create en utilisant la convention de nommage meta_=. Vous pouvez attacher n’importe quel nombre de paramètres meta à une seule réunion. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Les paramètres meta sont renvoyés dans les réponses de getMeetingInfo et getRecordings.
  • Les enregistrements peuvent être filtrés par valeurs meta en utilisant getRecordings?meta_=.
  • Les métadonnées des enregistrements peuvent être mises à jour ultérieurement via updateRecordings.

Paramètres meta de callback

Certains métaparamètres ont une signification particulière et déclenchent des callbacks HTTP lorsque des événements spécifiques se produisent. Ils permettent à votre application de réagir automatiquement aux événements du cycle de vie d’une réunion.

meta_endCallbackUrl

Déclenche une requête HTTP GET vers l’URL spécifiée lorsque la réunion se termine. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Propriété Valeur
Méthode HTTP GET
Déclencheur Lorsque la réunion se termine
Paramètres Callback meetingID — l’identifiant de la réunion
recordingmarks — true si l’enregistrement contient des marqueurs, sinon false

Exemple de requête de rappel : 

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

meta_bbb-recording-ready-url

Déclenche une requête HTTP POST lorsque l’enregistrement a été entièrement traité et publié. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Propriété Valeur
Méthode HTTP POST
Déclencheur Lorsque l’enregistrement est entièrement traité et publié
Sécurité Les paramètres sont signés par JWT (JSON Web Token)
Corps POST Contient des données signées avec des informations sur l’enregistrement

Ne confondez pas ce callback avec endCallbackUrl. Le traitement de l’enregistrement peut prendre un temps considérable après la fin de la réunion. Le callback recording-ready n’est déclenché qu’une fois le traitement terminé.

meta_analytics-callback-url

Déclenche une requête HTTP POST avec des données analytiques agrégées après la fin de la réunion. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Propriété Valeur
Méthode HTTP POST
Déclencheur Après la fin de la réunion (post-events hook)
Authentification Jeton JWT envoyé comme en-tête Authorization: Bearer (HS512, signé avec le secret partagé BBB, valable 24 heures)
Format du corps Objet JSON contenant version, meeting_id, internal_meeting_id, data
Contenu des données Durée de participation, statistiques d’activité, utilisation du chat et autres événements agrégés de la réunion

L’URL de callback analytique provient de la base de code BigBlueButton et n’est pas entièrement documentée dans la documentation officielle de l’API. Le schéma exact de l’objet de données analytiques n’est pas normalisé et peut changer selon les versions. undocumented

Notez la différence dans la livraison de JWT : analytics-callback-url envoie le JWT comme en-tête HTTP Authorization, tandis que bbb-recording-ready-url inclut le JWT directement dans le corps POST.

Paramètres d’anonymisation des enregistrements

Ces métaparamètres contrôlent si les noms des expéditeurs du chat sont anonymisés dans les enregistrements traités. Ils sont utiles pour la conformité en matière de confidentialité et les exigences de protection des données.

Paramètre Type Par défaut Description
meta_bbb-anonymize-chat Boolean false Anonymise les expéditeurs des messages de chat dans les enregistrements traités. N’affecte que les messages des participants (non-modérateurs). Les noms des modérateurs restent visibles.
meta_bbb-anonymize-chat-moderators Boolean false Anonymise en plus les expéditeurs des messages de chat des modérateurs dans les enregistrements. Nécessite généralement aussi que meta_bbb-anonymize-chat=true soit défini.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

Les paramètres d’anonymisation ne sont que brièvement mentionnés dans la documentation officielle de l’API. Leur comportement est déduit du code source BigBlueButton. undocumented

Paramètres d’intégration LMS

De nombreux plugins LMS définissent automatiquement des métaparamètres pour documenter l’origine d’une réunion. Ils sont informatifs et n’affectent pas le comportement de la réunion, mais ils sont utiles pour l’audit et le reporting.

Paramètre Exemple Description
meta_bbb-origin greenlight, moodle L’application source qui a créé la réunion.
meta_bbb-origin-version v3.1.0 Version de l’application source.
meta_bbb-origin-server-name api-guide.bbbserver.com Nom d’hôte de l’application source.
meta_bbb-context Course: Computer Science Informations de contexte telles que le nom du cours.
meta_bbb-context-id course-42 Identifiant de contexte pour une utilisation programmatique.

Bonnes pratiques pour les métaparamètres personnalisés

  • Utilisez des noms de clé descriptifs (par ex. meta_department, meta_project) qui indiquent clairement l’objectif de la valeur.
  • Encodez en URL les valeurs contenant des caractères spéciaux, des espaces ou des caractères non ASCII.
  • Utilisez des métaparamètres pour l’intégration avec des systèmes externes tels que CRMs, des plateformes d’apprentissage ou des tableaux de bord analytiques.
  • Mettez à jour les métadonnées d’enregistrement après coup à l’aide du point de terminaison updateRecordings pour ajouter ou corriger des métadonnées.

Combinez les métaparamètres avec le filtrage getRecordings pour créer de puissants workflows de recherche et de catégorisation de vos enregistrements. Par exemple, filtrez avec meta_department=engineering pour récupérer uniquement les enregistrements des réunions d’ingénierie.

Foire aux questions

Il n’existe pas de limite stricte au nombre de métaparamètres. Cependant, comme ils sont transmis en tant que paramètres de requête URL, vous devez rester dans des limites pratiques de longueur d’URL (généralement de 2 000 à 8 000 caractères selon la configuration du serveur web).

Les métaparamètres définis lors de l’appel create ne peuvent pas être modifiés pendant que la réunion est en cours. Cependant, les métadonnées d’enregistrement peuvent être mises à jour après le traitement à l’aide du point de terminaison updateRecordings.

Le endCallbackUrl se déclenche immédiatement à la fin de la réunion, en utilisant une simple requête GET. Le bbb-recording-ready-url se déclenche bien plus tard, seulement après que l’enregistrement a été entièrement traité et publié, et utilise une requête JWT signée par POST.

Les détails de signature du JWT ne sont pas entièrement spécifiés dans la documentation officielle. D’après le code source BigBlueButton, le JWT est signé à l’aide du secret partagé du serveur. Les revendications exactes et l’algorithme doivent être vérifiés par rapport à votre version spécifique de BigBlueButton.

La plupart des métaparamètres sont purement informatifs et ne modifient pas le fonctionnement de la réunion. Les exceptions sont les URL de callback, qui déclenchent des requêtes HTTP lors d’événements, et les paramètres d’anonymisation, qui influencent la manière dont les enregistrements sont traités.

Oui. Les clés des métaparamètres sont traitées comme des chaînes sensibles à la casse. Par exemple, meta_Department et meta_department seraient enregistrés comme deux paramètres distincts. Utilisez une casse cohérente dans votre intégration pour éviter les doublons.