Los widgets embebidos tienen mala reputación, y la merecen. Luchan contra tu CSS, bloquean tu página y se rompen cuando haces deploy. Aquí está lo que el nuestro hace en su lugar, en el orden en que pasa.
No bloquea nada
La etiqueta está diferida, así que se carga después de que tu página sea interactiva:
<script src="https://cdn.welcomeai.dev/widget/v1.js" data-wai-key="wg_tu_clave_aqui" defer></script>El bundle ocupa aproximadamente 20 KB comprimido. Es Preact en lugar de React, porque el widget no necesita reconciliar el árbol de nadie más.1
Se renderiza en una shadow root
Todo lo que dibuja el widget vive dentro de una shadow root con sus propios estilos. Tu CSS no puede entrar, y el nuestro no puede filtrarse hacia afuera.
Esta es la decisión única que elimina la mayoría de errores de embebido: sin conflictos de reset, sin guerra de especificidad, sin !important.
El costo es real, eso sí. No puedes rediseñar el widget desde tu propia hoja de estilos, porque tu hoja de estilos nunca lo alcanza.
El editor del widget cubre colores, radios, posición y textos. El campo de CSS personalizado se inyecta dentro de la shadow root, que es la única vía de entrada.
Sabe en qué página está
El widget envía la ruta actual con cada pregunta, y la recuperación da un pequeño impulso a los fragmentos de esa página. En una página de precios, una pregunta sobre "el límite" encuentra el contenido de precios primero.
Para una aplicación de una sola página también sigue la navegación del lado del cliente, así que el contexto es el correcto después de un cambio de ruta y no el de la página anterior.
Se niega a ejecutarse donde no debería
Una clave de widget vive en HTML público, y eso está bien siempre que la clave esté atada a algo. Cada solicitud lleva un token vinculado al origen, y el widget solo responde en los dominios que listaste.
Si alguien copia tu clave en su propio sitio, la solicitud se rechaza, y el rechazo nombra el origen que vimos:
[welcomeai] refused: origin "https://not-your-site.example" is not on the allow list for key wg_tu_clave_aquiEse mensaje aparece en la consola de tu navegador, lo que convierte un dominio de staging mal configurado en un arreglo de treinta segundos en lugar de una tarde.
Los deploy previews suelen recibir un hostname nuevo por build. Si quieres el widget respondiendo ahí, lista el patrón, no la única URL que tienes delante.
Preguntas frecuentes
¿Va a bajar mi puntaje de Lighthouse?
No debería. La etiqueta está diferida, así que el bundle no se descarga ni se parsea hasta después de que tu página sea interactiva, y nada de lo que hace el widget está en tu ruta crítica.
¿Puedo darle estilo con mi propio CSS?
No desde tu hoja de estilos, porque la shadow root lo bloquea en las dos direcciones. Usa el editor del widget para las propiedades comunes y el campo de CSS personalizado para todo lo demás.
¿Funciona en una single-page app?
Sí. Sigue los cambios de ruta del lado del cliente y actualiza el contexto de página que envía con cada pregunta.
¿Qué pasa si roto la clave?
La clave antigua deja de responder de inmediato, en todos los lugares donde esté pegada. Cambia la etiqueta antes de rotar, no después.
Pega la etiqueta en una página, abre tu consola, y comprueba que la primera respuesta vuelve con sus fuentes adjuntas.
