Version de l’API: 4.x dernière version 3.x
Chapitre 2

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
Avant (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
Après (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Dispositions

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.

Rappel (3.x)
GET https://example.com/ended?token=a817dde5
Rappel (4.0.1+)
GET https://example.com/ended?token=a817dde5
  &recordingmarks=true&meetingID=demo

Si 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 meetingKeepEvents de leur réunion parente (auparavant, elles utilisaient toujours la valeur par défaut du serveur defaultKeepEvents). Les salles de sous-groupes que vous créez vous-même via create avec isBreakout=true utilisent toujours leur propre paramètre meetingKeepEvents.

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.
Avant (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Après (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Modifications de insertDocument

  • Au maximum 10 documents par appel (maxPresentationsPerRequest). Les documents excédentaires sont ignorés ; la réponse reste SUCCESS avec messageKey=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 FAILED contient désormais un messageKey : 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/clientSettings a été supprimé. Les paramètres du client sont désormais fournis via GraphQL dans le client ; personnalisez-les pour chaque réunion avec clientSettingsOverride ou clientSettingsOverrideJsonUrl.
  • 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/ renvoient 404 avec 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 200 sans en-têtes Access-Control-* (auparavant 403) ; Vary: Origin n’est plus envoyé.
  • Toutes les réponses incluent les en-têtes de sécurité X-Frame-Options, X-Content-Type-Options, Referrer-Policy et X-XSS-Protection. Si vous intégrez des réponses de l’API dans des cadres, vérifiez X-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 role sur join (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

Vous pouvez – et devriez – le faire à l’avance. Les solutions de remplacement recommandées (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.

Non. BigBlueButton ignore les paramètres inconnus : un paramètre supprimé n’a donc aucun effet, sans que cela soit signalé. C’est pourquoi les paramètres supprimés passent facilement inaperçus : vérifiez votre code à l’aide des listes de ce guide.

Non. Le calcul de checksum reste sha(apiCallName + queryString + sharedSecret), avec les mêmes algorithmes de hachage pris en charge.

Non. Ce guide couvre uniquement les modifications des appels API effectués par votre application. La mise à niveau des serveurs de conférence eux-mêmes est un sujet distinct, pris en charge par l’opérateur de votre serveur.