Visión general
Los Custom Scripts permiten inyectar JavaScript y CSS personalizados en tres superficies de la plataforma:
- Panel (dashboard): el panel que usa tu equipo de atención.
- Portal: el sitio público del Centro de Ayuda.
- Widget: el chat embebido en tu sitio web.
Con esto agregas comportamientos (p. ej., rastrear eventos, mostrar un aviso) o ajustes de estilo (p. ej., ocultar/resaltar elementos) sin modificar el código de la plataforma. Es una función potente y, por eso, vive en la administración de la plataforma.
Requisitos previos
- Acceso de operador/super administración de la plataforma.
- Conocimiento de JavaScript/CSS (el script se ejecuta en el navegador de quien usa la superficie elegida).
- Un entorno para probar antes de publicar (idealmente fuera de producción).
Paso a paso
- Accede al panel de administración de la plataforma y abre el área de Custom Scripts.
- Crea un nuevo script indicando: superficie (panel, portal o widget), tipo (JS o CSS) y cuándo debe ejecutarse (run on).
- Pega tu código. En scripts JS, usa el objeto de contexto (
ctx) que ofrece la plataforma para interactuar de forma segura con la superficie. - Limpieza (teardown): los scripts que agregan elementos/escuchas deben eliminarlos cuando se solicite, para no acumular efectos secundarios en la navegación SPA.
- Guarda, activa y prueba en la superficie correspondiente antes de liberar para todos.
Configuración y opciones
- Superficie: elige en qué entorno se ejecuta el script (panel, portal o widget).
- Tipo: JavaScript (comportamiento) o CSS (estilo).
- Cuándo ejecutar (run on): controla el momento/contexto de ejecución.
- Activo/Inactivo: enciende o apaga un script sin borrarlo.
Fondo del login y scripts públicos
Las páginas de login, registro y solicitud de restablecimiento de contraseña ejecutan Custom Scripts de dashboard activos que coinciden con la ruta. El fondo gestionado del login usa ctx.dom.css; ctx.log y los helpers de limpieza también funcionan. En estas páginas públicas, ctx.store, ctx.api y ctx.storage no están disponibles, se excluyen scripts limitados a cuentas y no se envía el estado de ejecución a las API de cuenta. Los scripts siguen siendo JavaScript de confianza del operador, sin sandbox.
Usa run_on: route_change con /app/login* para estilos exclusivos del login; sus recursos gestionados se eliminan al salir de la ruta. La edición de contraseña sigue excluida, incluso durante la navegación SPA. Si la página inicial es la edición de contraseña, recarga una página permitida para cargar sus scripts. Tras aplicar la identidad visual, recarga el login; las páginas públicas no reciben hot reload autenticado.
Casos de uso
- Agregar un aviso/banner temporal en el panel del equipo.
- Ocultar o reestilizar un elemento del portal para combinar con tu marca.
- Disparar un evento de analítica cuando se abre el widget.
Consejos, límites y buenas prácticas
- Mantén los scripts pequeños e idempotentes; siempre implementa el teardown.
- Evita dependencias externas pesadas — afectan el rendimiento de la superficie.
- Versiona tu código fuera de la plataforma y documenta qué hace cada script.
- Al ser inyección de código, trátalo como alto impacto: revisa antes de publicar.
Solución de problemas
- El script no se ejecuta: revisa la superficie elegida, si está activo y el momento de ejecución (run on).
- Algo se rompió en pantalla: desactiva el script y usa la consola del navegador para ver errores.
- El efecto se duplica al navegar: falta el teardown — elimina elementos/escuchas agregados.
- No encuentro el área de Custom Scripts: está en la administración de la plataforma — pide acceso a quien gestiona la instalación.
Informes de ejecución
Los informes de error del navegador envían solo el estado de ejecución y el mensaje de error, sin stack trace, URL sin sanear ni metadatos del momento de ejecución. Los incidentes de tormenta reproducidos conservan la ruta saneada de la página; los scripts de marca administrados mantienen su exención de desactivación automática. Revisa los mensajes antes de compartirlos: un script puede incluir sus propios datos en un mensaje de error.