Migrer de la version 3.x à la version 4.x
BigBlueButton 4.0 supprime plusieurs paramètres et valeurs de disposition obsolètes, modifie plusieurs valeurs par défaut et introduit de nouvelles clés d’erreur. Ce guide répertorie tous les points à vérifier dans vos appels API lorsque votre intégration communique avec un serveur BigBlueButton 4.x plutôt qu’avec un serveur BigBlueButton 3.x.
Portée : Ce guide couvre les changements apportés aux appels API effectués par votre application (create, join, insertDocument, …). Il ne couvre pas la mise à niveau ni la migration des serveurs de conférence eux-mêmes.
Commençons par la bonne nouvelle : les points de terminaison, le calcul de checksum, le format de réponse XML et tous les points de terminaison liés aux enregistrements restent inchangés. La plupart des intégrations ne nécessitent que l’ajustement de quelques paramètres. Les paramètres inconnus ou supprimés sont ignorés sans avertissement : un paramètre supprimé ne provoque donc pas d’erreur, mais n’a plus aucun effet.
Vue d’ensemble de tous les changements
| Point de terminaison | Changement | Impact | Action requise |
|---|---|---|---|
create | lockSettingsDisableNote (au singulier) supprimé | Rupture de compatibilité | Utilisez lockSettingsDisableNotes. |
create | Le pont multimédia par défaut est désormais livekit | Changement de comportement | Vérifiez l’accès par téléphone avec la salle d’attente des invités ; définissez audioBridge si nécessaire. |
create | sharedNotesEditor ignoré – Etherpad supprimé | Changement de comportement | Supprimez le paramètre ; les notes partagées utilisent toujours BlockNote. |
create | meetingEndedURL reçoit meetingID et recordingmarks (4.0.1) | Changement de comportement | Assurez-vous que votre gestionnaire de rappel accepte les paramètres supplémentaires. |
create | Les salles de sous-groupes créées dans le client héritent de meetingKeepEvents de la réunion parente | Changement de comportement | Généralement aucune. |
create | La valeur par défaut de meetingLayout est désormais UNIFIED_LAYOUT | Changement de comportement | Généralement aucune ; transmettez explicitement meetingLayout pour utiliser l’une des dispositions spéciales. |
create | Nouvelles clés d’erreur malformedXml et invalidPresentationUrl ; la réunion n’est pas créée | Changement de comportement | Vérifiez votre gestion des erreurs pour les documents téléversés à l’avance. |
create | layouts et captions supprimés de disabledFeatures | Aucun impact fonctionnel | Supprimez les valeurs de votre liste. |
create | copyright, logoutTimer, webVoice supprimés | Aucun impact fonctionnel | Supprimez les paramètres (ils n’avaient aucun effet auparavant). |
create, insertDocument | 10 documents maximum par appel (4.0.1) | Changement de comportement | Gérez documentsDropped ou répartissez les téléversements sur plusieurs appels. |
create, join | Dispositions CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS et VIDEO_FOCUS supprimées | Changement de comportement | Utilisez UNIFIED_LAYOUT ou l’une des dispositions spéciales. |
create, join | Nouveaux paramètres lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation | Nouveauté | Facultatif. |
end | Met également fin aux salles de répartition créées via l’API | Changement de comportement | Supprimez les solutions de contournement qui mettaient fin séparément aux salles isBreakout. |
insertDocument | Limitation du débit et nouvelles clés d’erreur (4.0.1) | Changement de comportement | Gérez rateLimitExceeded et les nouvelles valeurs de messageKey. |
join | fullName limité à 255 caractères | Rupture de compatibilité | Tronquez les noms ; gérez fullNameTooLong. |
join | webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction et userdata-bbb_parent_room_moderator supprimés | Changement de comportement | Remplacez-les comme décrit ci-dessous. |
sendChatMessage | Nouvelles clés d’erreur pour les paramètres manquants | Changement de comportement | Gérez missingParamMeetingID et missingParamMessage. |
/api/rest/clientSettings | Point de terminaison supprimé | Rupture de compatibilité | Ne l’appelez plus ; utilisez clientSettingsOverride pour personnaliser les paramètres du client. |
Modifications de create
Paramètres supprimés
| Paramètre (3.x) | Statut dans la version 4.x | Remplacement |
|---|---|---|
lockSettingsDisableNote | Supprimé (il s’agissait d’un alias obsolète). Rupture de compatibilité | lockSettingsDisableNotes |
sharedNotesEditor | Ignoré. Etherpad a été supprimé, toutes les réunions utilisent BlockNote. | Aucun. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown et sharedNotesInitialContentMarkdownUrl fonctionnent désormais pour toutes les réunions, et non plus uniquement avec sharedNotesEditor=blockNote. |
copyright | Supprimé. La valeur n’était jamais transmise au client. | Paramètre du client public.app.copyright via clientSettingsOverride (nécessite allowOverrideClientSettingsOnCreateCall=true sur le serveur) ou clientSettingsOverrideJsonUrl. |
logoutTimer | Supprimé. La valeur n’était jamais transmise au client. | — |
webVoice | Supprimé. Obsolète depuis l’abandon du client Flash dans BBB 2.3. | voiceBridge |
create?meetingID=demo&name=Demo
&lockSettingsDisableNote=true
&sharedNotesEditor=blockNote
©right=Example+Inc.
&meetingLayout=SMART_LAYOUTcreate?meetingID=demo&name=Demo
&lockSettingsDisableNotes=true
&clientSettingsOverrideJsonUrl=https%3A%2F%2F
example.com%2Fclient-settings.json
&meetingLayout=UNIFIED_LAYOUTDispositions
Le choix de la disposition dans le client a été remplacé par une disposition adaptative unique. UNIFIED_LAYOUT est la nouvelle valeur par défaut de meetingLayout, et les dispositions classiques ne sont plus acceptées par meetingLayout (sur create), enforceLayout (sur join et getJoinUrl) et userdata-bbb_default_layout :
Les valeurs de disposition supprimées ne provoquent pas d’erreur : le client les ignore et utilise la source de disposition suivante (par exemple, la disposition de la réunion ou la disposition par défaut).
| Valeur dans la version 3.x | Statut dans la version 4.x | Valeur recommandée dans la version 4.x |
|---|---|---|
CUSTOM_LAYOUT (par défaut dans la version 3.x) | Supprimé | UNIFIED_LAYOUT |
SMART_LAYOUT | Supprimé | UNIFIED_LAYOUT |
PRESENTATION_FOCUS | Supprimé | UNIFIED_LAYOUT ; pour un écran dédié à la présentation (par exemple, un projecteur), PRESENTATION_ONLY |
VIDEO_FOCUS | Supprimé | UNIFIED_LAYOUT ; pour une mosaïque de caméras, CAMERAS_ONLY |
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY | Inchangé | — |
CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY et MEDIA_ONLY sont des dispositions spéciales destinées aux usages hybrides ou en mode kiosque : elles masquent de grandes parties de l’interface utilisateur. Ne les utilisez pas pour remplacer directement les dispositions supprimées dans les réunions ordinaires.
Passerelles multimédias
audioBridge, cameraBridge et screenShareBridge ont désormais pour valeur par défaut livekit au lieu de bbb-webrtc-sfu. La valeur freeswitch n’est plus valide pour audioBridge : le client la traite comme une passerelle inconnue et utilise désormais livekit comme solution de repli (auparavant bbb-webrtc-sfu). Utilisez audioBridge=bbb-webrtc-sfu à la place.
Les participants qui se connectent par téléphone au pont audio LiveKit ne passent pas par la salle d’attente des invités, même avec guestPolicy=ASK_MODERATOR. Si votre intégration repose sur l’admission des participants téléphoniques par les modérateurs, transmettez audioBridge=bbb-webrtc-sfu sur create, ce qui fait basculer le pont audio vers FreeSWITCH.
Remarque à l’attention des clients bbbserver.de : nous travaillons à maintenir la restriction d’accès par téléphone de BigBlueButton également lors de l’utilisation de LiveKit.
Les paramètres de userdata, userdata-bbb_listen_only_mode et userdata-bbb_transparent_listen_only, ne sont évalués qu’avec audioBridge=bbb-webrtc-sfu. Avec livekit, les utilisateurs en écoute seule rejoignent toujours la réunion via une connexion microphone dont le son est coupé.
Valeurs de disabledFeatures
| Valeur | Changement |
|---|---|
layouts | N’est plus valide : le choix de la disposition a été supprimé du client. Aucun impact fonctionnel |
captions | N’est plus valide : n’avait plus d’effet depuis BBB 3.0. Utilisez liveTranscription pour désactiver la transcription automatique. Aucun impact fonctionnel |
pinChatMessage | Nouveau : désactive l’épinglage des messages de discussion. Nouveauté |
multiFunctionalMode | Nouveau : désactive le panneau latéral auxiliaire. Nouveauté |
webcamGrid | Nouveau : désactive les vignettes d’avatar des utilisateurs sans caméra lorsque la présentation est réduite. Nouveauté |
Présentations téléversées à l’avance
Depuis BBB 4.0.1, un appel à create téléverse au maximum 10 documents (paramètre serveur maxPresentationsPerRequest ; la présentation par défaut n’est pas comptabilisée). Le document marqué current="true" est toujours conservé ; les autres suivent dans l’ordre de la requête. Les documents excédentaires sont ignorés, mais la réunion est tout de même créée et la réponse contient messageKey=documentsDropped :
<response>
<returncode>SUCCESS</returncode>
<meetingID>demo</meetingID>
<!-- ... -->
<messageKey>documentsDropped</messageKey>
<message>...</message>
</response> Notez que messageKey peut désormais être documentsDropped sur SUCCESS. Si votre code considère tout messageKey comme une erreur ou vérifie uniquement duplicateWarning, adaptez-le. Téléversez ensuite les documents supplémentaires avec insertDocument.
De plus, create vérifie désormais le corps de la requête avant la création de la réunion : un corps qui n’est pas un document XML bien formé entraîne un échec avec messageKey=malformedXml ; une URL de document dont la syntaxe est invalide entraîne un échec avec messageKey=invalidPresentationUrl. Dans les deux cas, la réunion n’est pas créée.
Rappel de fin de réunion
Depuis BBB 4.0.1, le rappel meetingEndedURL ajoute meetingID et recordingmarks à la chaîne de requête de votre URL (4.0.0 appelait l’URL sans la modifier). Les paramètres existants conservent leurs valeurs, mais peuvent être réencodés. Si votre URL contient déjà un paramètre du même nom, les deux valeurs sont envoyées, la vôtre en premier.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoSi vous utilisez encore meta_endCallbackUrl : la documentation officielle recommande désormais meetingEndedURL à la place, car les valeurs de meta_* peuvent être visibles par les utilisateurs de la réunion et risquent de divulguer des jetons secrets présents dans l’URL de rappel. Ne vérifiez pas de signature sur la chaîne de requête brute, car celle-ci peut être réencodée.
Autres modifications
- Les salles de sous-groupes créées dans le client héritent désormais de la valeur effective de
meetingKeepEventsde leur réunion parente (auparavant, elles utilisaient toujours la valeur par défaut du serveurdefaultKeepEvents). Les salles de sous-groupes que vous créez vous-même viacreateavecisBreakout=trueutilisent toujours leur propre paramètremeetingKeepEvents.
Nouveaux paramètres
| Paramètre | Par défaut | Description |
|---|---|---|
lockSettingsPresenterPolicy | requireApproval | Politique « Demander à présenter » : moderatorOnly, requireApproval ou freeForAll. |
requireUserConsentBeforeUnmuting | false | Avec true, les utilisateurs doivent donner leur accord avant qu’un modérateur ne réactive leur microphone (pertinent uniquement avec allowModsToUnmuteUsers=true). |
La valeur par défaut requireApproval signifie que les spectateurs peuvent désormais demander le rôle de présentateur dans le client. Si seuls les modérateurs doivent pouvoir attribuer le rôle de présentateur, transmettez lockSettingsPresenterPolicy=moderatorOnly.
Tous les détails : Créer une réunion (4.x).
Modifications de join
| Paramètre | Changement | Mesures à prendre |
|---|---|---|
fullName | Limité à 255 caractères. Les valeurs plus longues sont rejetées avec fullNameTooLong (auparavant, aucune limite). | Tronquez les noms d’affichage avant de construire l’URL permettant de rejoindre la réunion. |
enforceLayout | Seuls UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY et MEDIA_ONLY sont acceptés. | Convertissez les anciennes valeurs selon les correspondances indiquées dans le tableau des mises en page ci-dessus. |
webVoiceConf | Supprimé (la valeur n’était jamais lue). | Supprimez le paramètre. |
userdata-bbb_change_layout | Supprimé ; ses valeurs smart, videoFocus, presentationFocus et custom n’existent plus. | Utilisez userdata-bbb_default_layout. |
userdata-enable-user-reaction | Supprimé. | Utilisez disabledFeatures=userReactions sur create ou le paramètre client public.userReaction.enabled. |
userdata-bbb_parent_room_moderator | Supprimé dans 4.0.1 ; il n’avait aucun effet depuis 3.0.25. | Attribuez le rôle dans la salle de sous-groupe avec role. |
userdata-bbb_hide_sidebar_navigation | Nouveau : ferme la navigation latérale et le panneau latéral lorsque l’utilisateur rejoint la réunion. Nouveauté | Facultatif. |
join?meetingID=demo&role=VIEWER
&fullName=<any length>
&enforceLayout=PRESENTATION_FOCUS
&userdata-bbb_change_layout=smartjoin?meetingID=demo&role=VIEWER
&fullName=<max. 255 characters>
&enforceLayout=UNIFIED_LAYOUT
&userdata-bbb_default_layout=UNIFIED_LAYOUTModifications de insertDocument
- Au maximum 10 documents par appel (
maxPresentationsPerRequest). Les documents excédentaires sont ignorés ; la réponse resteSUCCESSavecmessageKey=documentsDropped. - Limite de fréquence par réunion : par défaut, 30 appels toutes les 60 secondes. Les appels dépassant la limite échouent avec
rateLimitExceeded; réessayez après un délai. - Chaque réponse
FAILEDcontient désormais unmessageKey:notFound,malformedXml,invalidPresentationUrl,invalidFilename,presentationDisabled,noDocuments.
Si votre gestion des erreurs compare le texte de message, utilisez plutôt messageKey. Détails : Insérer une présentation (4.x).
Modifications de end
Mettre fin à une réunion met désormais également fin à toutes ses salles de sous-groupes, y compris celles créées via create avec isBreakout=true. Auparavant, seules les salles de sous-groupes créées depuis le client se terminaient en même temps que leur réunion parente. Si votre application mettait fin à ces salles avec des appels end distincts, ces appels ne sont plus nécessaires ; assurez-vous que votre code gère le cas d’une salle de sous-groupe déjà terminée.
Modifications de sendChatMessage
Le messageKey pour les paramètres manquants a changé : l’absence de message renvoie désormais missingParamMessage (auparavant nullError), et l’absence de meetingID renvoie missingParamMeetingID (auparavant meetingNotFound). Les dépassements de longueur renvoient toujours sizeError, et les caractères invalides dans meetingID renvoient toujours validationError.
Points de terminaison supprimés et modifications au niveau HTTP
/api/rest/clientSettingsa été supprimé. Les paramètres du client sont désormais fournis via GraphQL dans le client ; personnalisez-les pour chaque réunion avecclientSettingsOverrideouclientSettingsOverrideJsonUrl.- Les parties de l’API GraphQL liées à Etherpad ont été supprimées. Les extensions ou intégrations qui les interrogent reçoivent une erreur de validation.
- Les URL inconnues sous
/bigbluebutton/renvoient404avec un corps JSON au lieu d’un document XML. - Les requêtes contenant plus de 10,000 paramètres reçoivent une réponse
HTTP 500. - Les requêtes préliminaires CORS sans configuration CORS renvoient
200sans en-têtesAccess-Control-*(auparavant403) ;Vary: Originn’est plus envoyé. - Toutes les réponses incluent les en-têtes de sécurité
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyetX-XSS-Protection. Si vous intégrez des réponses de l’API dans des cadres, vérifiezX-Frame-Options.
Les modifications concernant les réponses 404, la limite du nombre de paramètres et les requêtes préliminaires CORS s’appliquent déjà depuis BBB 3.0.40 (bbb-web sous Grails 8) ; elles ne vous concernent que si vos serveurs exécutent une version 3.0 antérieure. Les en-têtes de sécurité sont nouveaux dans 4.0 ; dans BBB 3.0.40, ils sont désactivés.
Inchangé
Les parties suivantes de l’API sont identiques dans 3.x et 4.x ; aucune modification n’est nécessaire :
- Calcul de Checksum et algorithmes de hachage pris en charge (SHA-1, SHA-256, SHA-384, SHA-512)
isMeetingRunning,getMeetings,getMeetingInfo(Paramètres et format de réponse)getRecordings,publishRecordings,deleteRecordings,updateRecordings,getRecordingTextTracks,putRecordingTextTrack- Webhooks, à l’exception de l’événement
pad-content, qui n’existe plus en raison de la suppression d’Etherpad - Attribution des rôles via
rolesurjoin(introduite dans BBB 2.4)
Paramètres du serveur influant sur le comportement de l’API
Ces paramètres sont configurés par l’administrateur du serveur dans bbb-web.properties, et non via les paramètres de l’API. Si vous exploitez vos propres serveurs ou si votre fournisseur modifie ces paramètres, le comportement de vos appels à l’API peut changer :
| Paramètre | Modification dans la version 4.x |
|---|---|
allowDuplicateExtUserid | Supprimé. Les connexions multiples avec le même userID sont désormais contrôlées par maxUserConcurrentAccesses. |
defaultMeetingLayout | Valeur par défaut : UNIFIED_LAYOUT (auparavant CUSTOM_LAYOUT). |
audioBridge, cameraBridge, screenShareBridge | Par défaut : livekit. |
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec | Nouvelles limites (valeurs par défaut : 10, 30, 60). |
accessControlAllowOrigin | Supprimé ; CORS se configure via grails.cors.*. |
Liste de vérification pour la migration
Recherchez les valeurs supprimées dans votre code : CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction et clientSettings.
Nettoyez disabledFeatures : supprimez layouts et captions.
Limitez les noms d’affichage à 255 caractères et gérez fullNameTooLong.
Vérifiez les téléversements de présentations : pas plus de 10 documents par appel create/insertDocument ; gérez documentsDropped et rateLimitExceeded.
Vérifiez votre gestionnaire de rappel pour meetingEndedURL : il doit accepter les paramètres supplémentaires meetingID et recordingmarks.
Choisissez les nouvelles valeurs par défaut : les demandes pour devenir présentateur (lockSettingsPresenterPolicy) et la salle d’attente des invités pour les participants par téléphone (audioBridge).
Effectuez des tests sur un serveur 4.x – en particulier les salles de sous-groupes, les téléversements de présentations et votre gestion des erreurs basée sur messageKey.
Votre intégration doit prendre en charge les deux versions pendant un certain temps ? Toutes les modifications ci-dessus sont compatibles dans un sens : UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout et les noms d’affichage de 255 caractères maximum fonctionnent également sur les serveurs BBB 3.0.19+. Utilisez-les partout et vos appels API fonctionneront sur les deux versions.
Vous cherchez la documentation précédente ? La documentation de référence complète de 3.x reste disponible, par exemple Créer une réunion (3.x).
Foire aux questions
UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) sont déjà prises en charge par BBB 3.0.19. Préparez votre code afin que la mise à niveau du serveur ne nécessite pas la publication simultanée d’une nouvelle version de votre application.sha(apiCallName + queryString + sharedSecret), avec les mêmes algorithmes de hachage pris en charge.