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

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.

Chapitre 19

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_url doit ê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

Non. Les paramètres userdata s’appliquent uniquement à la session unique initiée par l’appel join. Si l’utilisateur quitte puis rejoint à nouveau, les paramètres doivent être inclus de nouveau dans la nouvelle URL join.

Non. Les paramètres userdata sont conçus uniquement pour le point de terminaison join. Ils sont traités par le client lorsqu’un utilisateur rejoint une réunion et n’ont aucun effet sur l’appel create.

Oui. Comme ils font partie de la chaîne de requête de l’URL, ils sont inclus dans le calcul du checksum. Vous devez ajouter tous les paramètres userdata à la chaîne de requête avant de calculer le checksum.

Non. Le paramètre 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.

Dans BigBlueButton 3.0, les paramètres lus par le client sont répertoriés dans le guide d’administration (Customize, section « Passing user metadata to the client on join »). Le code source du client (appels à getFromUserSettings dans le client HTML5) fait autorité.