Descripción general del embed
Añade un agente flotante a un sitio web existente con un cargador seguro e independiente del framework.
Añade un agente flotante a un sitio web existente con un cargador seguro e independiente del framework.
Cómo funciona el embed#
embed.js añade un único lanzador fijo al documento anfitrión. Puede precargar el iframe oculto desde https://makeagent.fast para evaluar los activadores de la página antes del primer clic; el visitante abre el chat completo desde el lanzador o desde un activador. El CSS del sitio anfitrión no puede cambiar el estilo del chat. Los cambios en la página anfitriona solo se ejecutan mediante controladores de acciones de página registrados y aprobados por el propietario.
El cargador es público y no usa una clave de API. El acceso se controla con el interruptor Mostrar en mi sitio web del agente y con la lista de permitidos de orígenes padre exactos (Direcciones de sitio web permitidas). El slug del sitio es un identificador, no un secreto.
Requisitos previos#
Antes de copiar el código:
- Crea y prueba un agente en el panel.
- Usa el fragmento generado del agente; no es necesario activar su Agent link independiente.
- En la página Agente del agente, abre Publicar → Widget para sitio web. Si el widget aún no está activado, elige Activar embed; después confirma que Mostrar en mi sitio web esté activado.
- En Direcciones de sitio web permitidas, añade cada origen padre que mostrará el lanzador.
- Selecciona Guardar ajustes del embed y luego copia el fragmento generado.
Un origen contiene solo el esquema, el nombre de host y, opcionalmente, el puerto. Nunca incluye una ruta. Estos son cuatro orígenes distintos y deben añadirse por separado cuando los uses:
https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000No introduzcas https://example.com/pricing, *.example.com ni un comodín al final. Si en producción el dominio sin www redirige a www, añade a la lista de permitidos el origen que permanece en la barra de direcciones del navegador después de la redirección.
Instala el cargador#
Coloca un script antes de la etiqueta de cierre </body>, o usa el ciclo de vida solo para navegador que recomiende la guía de tu framework.
La hoja Widget para sitio web (página Agente → Publicar) copia esta estructura (slug del sitio, posición, etiqueta opcional y el ?v= para invalidar la caché). Conserva async. Conserva la consulta ?v= del fragmento para que los sitios anfitriones no fijen un cargador obsoleto.
<script
src="https://makeagent.fast/embed.js?v=20261022-open"
data-agent="YOUR_SITE_SLUG"
data-position="right"
async
></script>Solo data-agent es obligatorio. Atributos opcionales que el cargador realmente lee:
<script
src="https://makeagent.fast/embed.js?v=20261022-open"
data-agent="YOUR_SITE_SLUG"
data-position="right"
data-label="Ask us"
data-accent="#6d5ce7"
data-locale="en"
data-theme="light"
async
></script>No pongas una clave de API de MAF, una clave de proveedor, un token de conector, la identidad del visitante ni datos privados de clientes en ningún atributo data-*. No inventes atributos como data-api-key, data-z-index, data-offset o data-delay. data-maf-bootstrapped lo establece el cargador.
Configura los atributos#
Se leen solo desde la etiqueta de embed.js. El iframe acepta únicamente acentos en formato hexadecimal.
| Atributo | Valor aceptado | Predeterminado | Efecto |
|---|---|---|---|
data-agent | Slug del sitio del agente | Obligatorio | Selecciona el sitio y el agente. Si falta → aviso en la consola, sin lanzador |
data-position | bottom-left, bottom-right, top-left, top-right (left / right siguen significando las esquinas inferiores) | right (bottom-right) | Cualquier otro valor se trata como bottom-right |
data-label | Texto sin formato | Solo icono | Texto visible del lanzador y nombre accesible. Escapa ", <. La interfaz del panel limita a 40 caracteres |
data-accent | #RGB o #RRGGBB | Apariencia guardada del sitio | Anulación del anfitrión para el lanzador; los valores que no sean hexadecimales se ignoran en el iframe |
data-locale | en, ko, uz o ru | Idioma principal del agente | Idioma con el que el agente inicia en esta página anfitriona, elegido entre sus idiomas habilitados |
data-theme | light o dark | Fondo del anfitrión; si no, el del sistema operativo | Se ignoran otros valores |
data-auto-form-error | true | Desactivado | Activa los eventos de activación por error de formulario; informa del ID del formulario, nunca de los valores de los campos |
data-analytics | off (también false, 0, no) | Activado | Úsalo cuando tu visitante no haya dado su consentimiento para analíticas: el marco del chat no carga analíticas de página ni envía la señal de visualización. El chat sigue funcionando |
El elemento raíz generado también usa data-maf-open internamente para saber si el chat está abierto. No es un ajuste de la etiqueta script ni un comando público para abrir el widget. Consulta Seguimientos para conocer el comportamiento de los activadores.
Sin data-theme, el cargador toma una muestra del fondo del sitio anfitrión y, si no, recurre a la preferencia del sistema operativo del visitante. También pasa al marco la familia tipográfica del anfitrión y obtiene la última apariencia del lanzador. Si la solicitud de apariencia falla, el lanzador no se bloquea; conserva el estilo seguro predeterminado. Los cambios en Pantalla en el panel actualizan esta consulta sin necesidad de volver a publicar el sitio.
Comportamiento en ejecución#
- Carga el script una sola vez por documento. Repetir el mismo slug es idempotente y sigue generando una única raíz
maf-embed-root-YOUR_SITE_SLUG. - Pueden coexistir distintos agentes en un mismo documento. El cargador marca cada script procesado con
data-maf-bootstrappedpara que un respaldo asíncrono inicialice cada etiquetadata-agentdistinta exactamente una vez. - El iframe puede precargarse para los activadores de página. Permanece oculto hasta que aparece un activador o el visitante abre el chat; las sesiones que ya usaron un activador mantienen la ruta de apertura diferida. El micrófono, la reproducción automática y la escritura en el portapapeles siguen sujetos al modelo de permisos de iframe del navegador.
- En una aplicación con enrutamiento del lado del cliente, monta el cargador en el diseño de nivel más alto que deba contenerlo para que los cambios de ruta no recarguen la conversación.
- Eliminar solo el elemento script no elimina un lanzador ya creado. Para desmontarlo en una ruta específica, elimina también el elemento
maf-embed-root-...correspondiente. Vuelve a cargar el script después del desmontaje para montarlo de nuevo. - El marco y el cargador intercambian mensajes con espacio de nombres sobre ciclo de vida, identidad, activadores y acciones de página. El cargador rechaza los mensajes que no procedan del origen de Make Agent Fast y del slug del sitio actual.
Verifica la instalación#
Prueba la página publicada, no solo la vista previa del editor de un creador de sitios web:
- Abre la URL desplegada en una ventana privada y confirma que su origen exacto está en la lista de permitidos.
- Confirma que
https://makeagent.fast/embed.js?v=20261022-opendevuelve200en el panel Red. - Confirma que existe un único elemento con
data-maf-embed="YOUR_SITE_SLUG". - Abre el lanzador y confirma que la solicitud del iframe a
/embed/YOUR_SITE_SLUGse realiza correctamente. - Envía una pregunta realista y confirma que aparece en Conversaciones.
- Prueba en una ventana de visualización móvil estrecha y, si está habilitado, el permiso del micrófono.
Diagnostica un lanzador que no aparece#
| Síntoma | Causa probable | Solución |
|---|---|---|
La consola avisa missing data-agent | El atributo del slug no está o se encuentra en otro script | Pon data-agent en la etiqueta de embed.js |
embed.js está bloqueado | Una CSP o un gestor de consentimiento rechazó el script | Permite el origen del script o cárgalo después del consentimiento requerido |
| El lanzador aparece pero el marco no carga | El embed está desactivado o el origen padre no coincide | Revisa de nuevo Mostrar en mi sitio web y Direcciones de sitio web permitidas en el panel |
| Funciona en localhost pero no en producción | Solo el origen de desarrollo está en la lista de permitidos | Añade el origen HTTPS exacto del sitio desplegado |
| Aparecen dos agentes distintos | El documento carga dos slugs diferentes | Conserva solo el slug del sitio deseado |
| El chat se abre pero la voz no funciona | El permiso del navegador o la Permissions Policy bloquea el micrófono | Sigue Seguridad y CSP |
Elige una guía de instalación#
Usa HTML y JavaScript para una etiqueta script normal. Para React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace o Ghost, elige la guía correspondiente en la barra lateral. Las plataformas que no permiten JavaScript arbitrario, como muchas superficies de Notion y Linktree, pueden enlazar al Agent link del agente: una página de chat pública en la dirección propia del agente, que se activa en el último paso de la incorporación (Pruébalo en tu teléfono) y en la pestaña Pantalla de la página Agente. Otra opción es un sitio web de cliente con el embed.
Para agentes de programación#
¿Vas a instalarlo en el sitio de un cliente con Claude Code, Cursor o Codex? Copia skills/embed-agent/SKILL.md del repositorio de Make Agent Fast en .cursor/skills/embed-agent/ o .claude/skills/embed-agent/. Ese archivo es la receta de instalación (atributos, CSP, ubicación). Esta página sigue siendo la guía para personas.