Capítulo 19

userdata – Configuración del cliente

Los parámetros userdata te permiten sobrescribir configuraciones del lado del cliente por usuario añadiendo parámetros con prefijo userdata- a la llamada API join. Esto te permite personalizar la experiencia de BigBlueButton para participantes individuales sin cambiar la configuración del servidor.

La lista de parámetros userdata disponibles solo está cubierta parcialmente por la documentación oficial de BigBlueButton. Muchos parámetros se derivan del análisis del código fuente de settings.yml y pueden cambiar entre versiones sin previo aviso. undocumented

Cómo funcionan los parámetros userdata

Los parámetros userdata se pasan como parámetros de consulta URL en la solicitud join. Sobrescriben los valores predeterminados de settings.yml solo para esa sesión de usuario. Los nombres de los parámetros siempre comienzan con el prefijo userdata- seguido de la clave de configuración. 

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

Como los parámetros userdata forman parte de la cadena de consulta, se incluyen en el cálculo de checksum. Asegúrate de añadirlos antes de calcular checksum, no después.

Parámetros de audio y medios

Parámetro Tipo Predeterminado Descripción
userdata-bbb_auto_join_audio Boolean — Unirse automáticamente al puente de audio cuando el usuario entra en la reunión.
userdata-bbb_listen_only_mode Boolean — Activa o desactiva el modo listen-only para el usuario.
userdata-bbb_force_listen_only Boolean — Fuerza al usuario al modo listen-only. Esto no se aplica a los moderadores.
userdata-bbb_skip_check_audio Boolean — Omitir el diálogo de prueba de audio al unirse.
userdata-bbb_skip_echotest_if_previous_device Boolean — Omitir la prueba de eco si se detecta el mismo dispositivo de audio que en la sesión anterior.

Parámetros de cámara web

Parámetro Tipo Predeterminado Descripción
userdata-bbb_auto_share_webcam Boolean — Iniciar automáticamente el uso compartido de la cámara web cuando el usuario se una.
userdata-bbb_mirror_own_webcam Boolean — Reflejar horizontalmente la vista previa de la propia cámara web del usuario.

Parámetros de diseño y visualización

Parámetro Tipo Predeterminado Descripción
userdata-bbb_auto_swap_layout Boolean — Cambiar automáticamente el diseño cuando se comparta una presentación.
userdata-bbb_default_layout String — Establecer el diseño predeterminado para el usuario. Los valores disponibles dependen de la configuración del cliente. undocumented
userdata-bbb_hide_presentation Boolean — Ocultar el área de presentación al usuario.
userdata-bbb_prefer_dark_theme Boolean — Activar el tema oscuro para la interfaz de usuario.

Parámetros de personalización y marca

Parámetro Tipo Predeterminado Descripción
userdata-bbb_custom_style String — Reglas CSS en línea (codificadas en URL) aplicadas al cliente BigBlueButton para este usuario.
userdata-bbb_custom_style_url URL — URL a un archivo CSS externo cargado por el cliente para estilos personalizados. Debe servirse a través de HTTPS.

El parámetro userdata-bbb_custom_style puede explotarse para cross-site scripting si las URL de join se construyen en el lado del cliente. Genera siempre las URL de join en el servidor, donde controlas los valores de los parámetros.

Parámetros de elementos de la interfaz

Parámetro Tipo Predeterminado Descripción
userdata-bbb_hide_notifications Boolean — Ocultar las notificaciones emergentes en la interfaz del cliente.
userdata-bbb_hide_controls Boolean — Ocultar al usuario los elementos de control de la interfaz (botones de la barra de herramientas).
userdata-bbb_shortcuts String — Definir atajos de teclado personalizados para el usuario.

Parámetros de grabación y control externo

Parámetro Tipo Predeterminado Descripción
userdata-bbb_outside_toggle_recording Boolean — Permitir que una aplicación externa active y desactive la grabación de la reunión.
userdata-bbb_outside_toggle_self_voice Boolean — Permitir que una aplicación externa active y desactive el audio del usuario.

Parámetros de la pizarra

Parámetro Tipo Predeterminado Descripción
userdata-bbb_initial_selected_tool String — Establece la herramienta de pizarra seleccionada inicialmente cuando el usuario abre la pizarra. Los valores aceptados están determinados por la configuración del cliente. undocumented

Ejemplos prácticos

A continuación se muestran combinaciones comunes de parámetros userdata para casos de uso típicos.

Modo quiosco

Ideal para pantallas de salas de conferencias o señalización digital donde no se requiere interacción del usuario: 

userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true

Marca específica del inquilino

Aplica una hoja de estilos CSS personalizada por tenant o cliente: 

userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css

Acceso rápido accesible

Simplifica el proceso de acceso para usuarios que necesitan una experiencia simplificada y accesible: 

userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true

Notas importantes

  • Los parámetros userdata solo afectan a la sesión actual del usuario individual. No cambian los valores predeterminados del servidor.
  • No todos los parámetros están disponibles en todas las versiones de BigBlueButton. Prueba con tu versión de destino antes de desplegar.
  • CSS cargado mediante userdata-bbb_custom_style_url debe servirse a través de HTTPS.

Al usar el endpoint getJoinUrl, ciertos parámetros userdata están bloqueados para los espectadores (rol VIEWER) como medida de seguridad. La lista de bloqueo se configura del lado del servidor mediante la propiedad getJoinUrlUserdataBlocklist en bigbluebutton.properties. Esto evita que los espectadores sobrescriban configuraciones críticas de seguridad del cliente mediante URL de join prefirmadas. undocumented

Preguntas frecuentes

No. Los parámetros userdata se aplican solo a la sesión iniciada por la llamada join. Si el usuario sale y vuelve a entrar, los parámetros deben incluirse de nuevo en la nueva URL de join.

No. Los parámetros userdata están diseñados solo para el endpoint join. Son procesados por el cliente cuando un usuario se une a una reunión y no tienen efecto en la llamada create.

Sí. Como forman parte de la cadena de consulta de la URL, se incluyen en el cálculo de checksum. Debes añadir todos los parámetros userdata a la cadena de consulta antes de calcular checksum.

No. El parámetro userdata-bbb_force_listen_only solo se aplica a los espectadores. Los moderadores no son forzados al modo listen-only independientemente de esta configuración.

La documentación oficial solo cubre un subconjunto. La lista más completa y actualizada se encuentra en el archivo settings.yml dentro del código fuente del cliente BigBlueButton. Se añaden nuevos parámetros con frecuencia sin actualizaciones en la documentación.