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.
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_urldebe 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
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.getFromUserSettings en el cliente HTML5) es la referencia definitiva.