Vous consultez la documentation de l’API pour BigBlueButton 3.x. La version actuelle est BigBlueButton 4.x. Vous prévoyez une mise à niveau ? Le guide de migration répertorie toutes les modifications à apporter à vos appels API.
userdata – Paramètres client
Les paramètres userdata vous permettent de remplacer les paramètres côté client pour chaque utilisateur en ajoutant des paramètres préfixés par userdata- à l’appel API join. Cela vous permet de personnaliser l’expérience BigBlueButton pour chaque participant sans modifier la configuration du serveur.
Dans BigBlueButton 3.0, les paramètres userdata ne sont pas répertoriés dans la référence de l’API, mais dans le guide d’administration (Customize, section « Passing user metadata to the client on join »). Ces paramètres peuvent changer d’une version à l’autre sans préavis.
Fonctionnement des paramètres userdata
Les paramètres userdata sont transmis comme paramètres de requête URL dans la requête join. Ils remplacent les valeurs par défaut de settings.yml pour cette seule session utilisateur. Les noms de paramètres commencent toujours par le préfixe userdata- suivi de la clé du paramètre.
GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&userdata-bbb_auto_join_audio=true&userdata-bbb_skip_check_audio=true&checksum=replace-with-checksum Étant donné que les paramètres userdata font partie de la chaîne de requête, ils sont inclus dans le calcul du checksum. Assurez-vous de les ajouter avant de calculer le checksum, et non après.
La partie située après userdata- ne doit pas contenir d’autre trait d’union ; sinon, le paramètre est ignoré. Le préfixe userdata-bbb_ est réservé à BigBlueButton ; les intégrations qui ajoutent leurs propres données par utilisateur doivent utiliser leur propre préfixe, par exemple userdata-myapp_cohort=2026A. Ces paramètres sont stockés avec l’utilisateur et consignés dans les événements d’enregistrement, mais ignorés par le client.
Paramètres audio et multimédia
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_auto_join_audio | Boolean | — | Rejoindre automatiquement le pont audio lorsque l’utilisateur entre dans la réunion. |
userdata-bbb_listen_only_mode | Boolean | — | Activer ou désactiver le mode listen-only pour l’utilisateur. |
userdata-bbb_force_listen_only | Boolean | — | Forcer l’utilisateur en mode listen-only. Cela ne s’applique pas aux modérateurs. |
userdata-bbb_skip_check_audio | Boolean | — | Ignorer la boîte de dialogue de test audio lors de la connexion. |
userdata-bbb_skip_echotest_if_previous_device | Boolean | — | Ignorer le test d’écho si le même périphérique audio que lors de la session précédente est détecté. |
Paramètres de webcam
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_auto_share_webcam | Boolean | — | Commencer automatiquement le partage de la webcam lorsque l’utilisateur rejoint la réunion. |
userdata-bbb_mirror_own_webcam | Boolean | — | Miroir horizontal de l’aperçu de la propre webcam de l’utilisateur. |
Paramètres de mise en page et d’affichage
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_default_layout | String | — | Disposition initiale du client. enforceLayout sur join est prioritaire ; si aucun des deux n’est défini, la disposition de la réunion est utilisée. Accepte les mêmes valeurs que meetingLayout sur create. BBB 3.0+ |
userdata-bbb_change_layout Removed in 4.0 | String | — | Ancien sélecteur de disposition. Accepte les mêmes valeurs que meetingLayout sur create (par exemple SMART_LAYOUT) et est prioritaire sur userdata-bbb_default_layout. Utilisez plutôt userdata-bbb_default_layout. |
userdata-bbb_hide_presentation_on_join | Boolean | false | Démarrer avec la zone de présentation réduite ; l’utilisateur peut la restaurer. BBB 2.6+ |
userdata-bbb_prefer_dark_theme | Boolean | — | Activer le thème sombre pour l’interface utilisateur. |
Paramètres de personnalisation et de marque
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_custom_style | String | — | Règles CSS en ligne (encodées URL) appliquées au client BigBlueButton pour cet utilisateur. |
userdata-bbb_custom_style_url | URL | — | URL vers un fichier CSS externe chargé par le client pour un style personnalisé. Doit être servi via HTTPS. |
Le paramètre userdata-bbb_custom_style peut être exploité pour CSS injection si les URL join sont construites côté client. Générez toujours les URL join sur le serveur, où vous contrôlez les valeurs des paramètres.
Paramètres des éléments de l’interface utilisateur
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_hide_notifications | Boolean | — | Masquer les fenêtres contextuelles de notification dans l’interface du client. |
userdata-bbb_hide_controls | Boolean | — | Masquer les éléments de contrôle de l’interface (boutons de la barre d’outils) pour l’utilisateur. |
userdata-bbb_shortcuts | String | — | Tableau JSON des raccourcis clavier qui restent activés (par ex. ["toggleMute","raiseHand"]) ; un tableau vide désactive tous les raccourcis. |
userdata-enable-user-reaction Removed in 4.0 | Boolean | — | Lu par le client, mais bbb-web supprime tout paramètre userdata- dont la clé contient un trait d’union. Ce paramètre ne parvient donc jamais au client et n’a aucun effet. Utilisez plutôt la valeur userReactions de disabledFeatures. |
Paramètres du tableau blanc
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
userdata-bbb_initial_selected_tool | String | — | Définissez l’outil de tableau blanc sélectionné initialement lorsque l’utilisateur ouvre le tableau blanc. Les valeurs acceptées sont déterminées par la configuration du client. |
Exemples pratiques
Vous trouverez ci-dessous des combinaisons courantes de paramètres userdata pour des cas d’usage typiques.
Mode kiosque
Idéal pour les écrans de salles de conférence ou l’affichage dynamique lorsqu’aucune interaction utilisateur n’est requise :
userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true Image de marque spécifique au locataire
Appliquer une feuille de style CSS personnalisée par locataire ou client :
userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css Rejoindre rapidement en mode accessible
Simplifiez le processus de connexion pour les utilisateurs ayant besoin d’une expérience simplifiée et accessible :
userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true Remarques importantes
- Les paramètres userdata n’affectent que la session actuelle de l’utilisateur individuel. Ils ne modifient pas les valeurs par défaut du serveur.
- Tous les paramètres ne sont pas disponibles dans chaque version de BigBlueButton. Testez avec votre version cible avant le déploiement.
- CSS chargé via
userdata-bbb_custom_style_urldoit être servi via HTTPS.
Lors de l’utilisation du point de terminaison getJoinUrl, certains paramètres userdata sont bloqués pour les spectateurs (rôle VIEWER) comme mesure de sécurité. La liste de blocage est configurée côté serveur via la propriété getJoinUrlUserdataBlocklist dans bigbluebutton.properties. Cela empêche les spectateurs de remplacer des paramètres client critiques pour la sécurité via des URL join pré-signées. Dans les salles de sous-groupes, la liste de blocage s’applique également aux modérateurs. undocumented
Foire aux questions
userdata-bbb_force_listen_only ne s’applique qu’aux spectateurs. Les modérateurs ne sont pas forcés en mode listen-only, indépendamment de ce paramètre.getFromUserSettings dans le client HTML5) fait autorité.