Versión de la API: 4.x más reciente 3.x

Estás viendo la documentación de la API de BigBlueButton 3.x. La versión actual es BigBlueButton 4.x. ¿Planeas una actualización? La guía de migración enumera todos los cambios que necesitan tus llamadas a la API.

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.

En BigBlueButton 3.0, los parámetros userdata no se enumeran en la referencia de la API, sino en la guía de administración (Customize, sección "Passing user metadata to the client on join"). Los parámetros pueden cambiar entre versiones sin previo aviso.

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.

La parte posterior a userdata- no debe contener otro guion; de lo contrario, el parámetro se descarta. El prefijo userdata-bbb_ está reservado para BigBlueButton; las integraciones que adjunten sus propios datos por usuario deben usar su propio prefijo, por ejemplo, userdata-myapp_cohort=2026A. Estos parámetros se almacenan con el usuario y se escriben en los eventos de grabación, pero el cliente los ignora.

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_default_layout String — Disposición con la que se inicia el cliente. enforceLayout en join tiene prioridad; si no se especifica ninguno de los dos, se usa la disposición de la reunión. Acepta los mismos valores que meetingLayout en create. BBB 3.0+
userdata-bbb_change_layout Removed in 4.0 String — Selector de disposición heredado. Acepta los mismos valores que meetingLayout en create (por ejemplo, SMART_LAYOUT) y tiene prioridad sobre userdata-bbb_default_layout. Usa userdata-bbb_default_layout en su lugar.
userdata-bbb_hide_presentation_on_join Boolean false Iniciar con el área de presentación minimizada; el usuario puede restaurarla. BBB 2.6+
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 CSS injection 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 — Array JSON de los atajos de teclado que permanecen habilitados (p. ej., ["toggleMute","raiseHand"]); un array vacío deshabilita todos los atajos.
userdata-enable-user-reaction Removed in 4.0 Boolean — El cliente lo lee, pero bbb-web descarta todos los parámetros userdata- cuya clave contiene un guion, por lo que este parámetro nunca llega al cliente y no tiene ningún efecto. Utilice el valor userReactions de disabledFeatures en su lugar.

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.

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. En las salas de grupos, la lista de bloqueo también se aplica a los moderadores. 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.

En BigBlueButton 3.0, los parámetros que lee el cliente se enumeran en la guía de administración (Customize, sección "Passing user metadata to the client on join"). El código fuente del cliente (las llamadas a getFromUserSettings en el cliente HTML5) es la referencia definitiva.