Seatext library

Cómo agregar el fragmento de IA de SeaText a tu sitio web para una integración general

Copia el fragmento de IA de SeaText desde tu panel de control y pégalo en la etiqueta <head> de cada página que quieras personalizar. Verifica que el script se cargue, comprueba que los agentes...

Cómo agregar el fragmento de IA de SeaText a tu sitio web para una integración general

Agregar el fragmento de IA de SeaText a tu sitio toma menos de un minuto. El fragmento es una pequeña etiqueta de JavaScript que se carga de forma asíncrona, almacena una ID de visitante en el almacenamiento local y comienza a reescribir texto, traducir contenido o hacer coincidir páginas de destino con palabras clave de anuncios, según los agentes que actives.

Qué hace el fragmento y por qué es importante

El fragmento de SeaText inyecta un script de cliente ligero (menos de 15 KB) en la página. Cuando el script se ejecuta, lee los parámetros de la URL, el contexto del visitante y la configuración de idioma. Luego activa los agentes de IA que hayas activado en el panel de control. Los agentes pueden reescribir titulares, traducir texto o hacer coincidir páginas de destino con palabras clave de búsqueda pagada.

Esto es importante porque permite que una sola página canónica sirva muchas experiencias personalizadas. Evitas crear docenas de páginas de destino estáticas, reduces la tasa de rebote y mejoras las métricas de conversión.

Cómo se comporta el fragmento al cargar la página

El fragmento incluye el atributo async, por lo que el navegador lo obtiene sin bloquear el renderizado. Según la documentación, el script se ejecuta en menos de 15 ms antes de la primera pintura. Este tiempo asegura que no haya cambios visuales (CLS = 0) y preserva las puntuaciones de PageSpeed.

Looking to implement this for your website?
Aprende más →

Al cargar, el script escribe una ID de visitante única en localStorage. La ID persiste a través de las vistas de página y las sesiones, lo que permite a los agentes mantener la continuidad para el mismo usuario.

Si la página es una aplicación de una sola página (SPA), el fragmento se ejecuta una vez cuando se carga el shell HTML inicial. Los cambios de ruta posteriores no recargan el script, por lo que los agentes continúan funcionando siempre que la SPA no recargue la página.

Requisitos previos antes de comenzar

Necesitas una cuenta de SeaText y un proyecto activo. Inicia sesión, abre el proyecto y copia el fragmento etiquetado como SEATEXTCODEINTEGRATION desde la página de instalación. El fragmento ya incluye el atributo async, por lo que no bloqueará el renderizado de la página. Tu sitio debe permitir scripts de terceros y permitir el acceso a localStorage; de lo contrario, la ID de visitante no puede persistir entre sesiones.

Si tu sitio abarca múltiples dominios o subdominios, confirma que el script pueda cargarse de forma cruzada sin ser bloqueado por las políticas de seguridad de contenido (CSP). La documentación señala que los problemas de origen cruzado pueden impedir que el fragmento se inicialice en dominios secundarios.

Integración general para sitios tradicionales de múltiples páginas

  1. Abre el archivo de plantilla o diseño HTML que envuelve cada página (a menudo header.php, layout.html o un _Layout.cshtml compartido).
  2. Pega el fragmento dentro de la etiqueta <head>, antes de cualquier otro script de terceros.
  3. Guarda y despliega el cambio en el entorno de pruebas o producción.
  4. Visita algunas páginas y abre las Herramientas de Desarrollo (F12). En las pestañas Consola y Red deberías ver que el script de SeaText se carga sin errores.

Eso es todo lo que se requiere para sitios estándar renderizados en el servidor. El fragmento se ejecutará en cada vista de página y aplicará los agentes activos automáticamente.

Integración para aplicaciones de una sola página (React, Vue, Angular)

Las SPA se montan una vez y luego intercambian vistas en el cliente, por lo que el fragmento debe estar en el shell HTML inicial o en el archivo de arranque del framework.

React

  1. Localiza public/index.html (Create React App) o tu punto de entrada HTML personalizado.
  2. Inserta el fragmento dentro de la etiqueta <body>, justo antes del cierre </body>.
  3. Ejecuta npm start o tu comando de compilación y verifica en la Consola que el script se cargue.

Vue.js

  1. Abre index.html en la raíz del proyecto (Vite) o public/index.html (Vue CLI).
  2. Coloca el fragmento en la sección <body>.
  3. Ejecuta npm run serve y revisa la pestaña Red para ver la solicitud de SeaText.

Angular

  1. Edita src/index.html.
  2. Agrega el fragmento dentro de <body>.
  3. Ejecuta ng serve y confirma que el script aparezca en la Consola sin violaciones de CSP.

La documentación enfatiza identificar el punto de entrada de la SPA — típicamente index.html o el archivo principal de arranque de TypeScript — e insertar el fragmento allí para que se cargue antes de que se renderice la primera ruta.

Integración con gestores de etiquetas y herramientas de consentimiento

Si usas Google Tag Manager (GTM) u otro gestor de etiquetas, crea una etiqueta HTML personalizada que contenga el fragmento de SeaText. Configura la etiqueta para que se dispare en Page View – All Pages y colócala al principio de la secuencia de etiquetas. Esto asegura que el script se ejecute antes que otras etiquetas de marketing.

Cuando una plataforma de gestión de consentimiento bloquea localStorage o scripts de terceros, el fragmento no puede almacenar la ID de visitante y omitirá la personalización. Configura tu herramienta de consentimiento para permitir el dominio de SeaText y el acceso a localStorage después de que el usuario dé consentimiento de marketing.

Consideraciones de rendimiento y privacidad

El fragmento tiene menos de 15 KB y se carga de forma asíncrona, por lo que añade un ancho de banda insignificante. El tiempo de ejecución se mide en menos de 15 ms antes de la primera pintura, manteniendo el desplazamiento acumulado de diseño en cero (CLS = 0). Este perfil de rendimiento cumple con los umbrales de Core Web Vitals.

En cuanto a la privacidad, el script solo escribe un identificador aleatorio en localStorage. No se envían datos personales hasta que un agente necesita obtener contenido de los servidores de SeaText. Todas las llamadas de red se realizan a través de HTTPS.

Si operas bajo regulaciones de privacidad estrictas, puedes deshabilitar el fragmento mediante una bandera en la capa de datos hasta que el usuario consienta. El fragmento permanecerá inactivo y no creará la ID de localStorage.

Pasos de verificación que aplican a cada integración

  1. Compila y sirve tu aplicación usando el comando estándar para tu stack.
  2. Abre las Herramientas de Desarrollo (F12) y cambia a las pestañas Consola y Red.
  3. Confirma que el script de SeaText se carga con un estado 200 y sin mensajes de error en rojo.
  4. Revisa localStorage: escribe localStorage.getItem('seatext_visitor_id') en la Consola. Un valor no nulo significa que la ID se creó.
  5. Verificación de funcionalidad: activa un agente (por ejemplo, agrega utm_term=shoes a la URL para probar la coincidencia de palabras clave, o cambia el idioma del navegador para probar la traducción).

Si algún paso falla, ve a la sección de solución de problemas.

Solución de problemas

  • Bloqueos de CSP: Asegúrate de que tu política de seguridad de contenido incluya script-src https://cdn.seatext.com y connect-src https://api.seatext.com. Agrega unsafe-inline solo si debes permitir el fragmento en línea (el fragmento proporcionado es autocontenido, por lo que rara vez se necesita).
  • Errores de origen cruzado: Verifica que la URL del script sea accesible desde todos los dominios. Si alojas el fragmento en un CDN, incluye ese dominio en tu CSP.
  • localStorage no disponible: El modo incógnito o el consentimiento estricto de cookies pueden deshabilitar localStorage. La consola mostrará una advertencia como “localStorage is not available”. Ajusta tu configuración de consentimiento o recurre a sessionStorage.
  • El fragmento no se dispara en GTM: Comprueba que la etiqueta HTML personalizada esté configurada para dispararse antes que otras etiquetas. Usa el modo de vista previa de GTM para ver el orden de las etiquetas.
  • Múltiples dominios: Agrega cada dominio en la configuración del proyecto de SeaText. El mismo fragmento funciona en todos los dominios siempre que el origen esté permitido.

Errores comunes a evitar

  • Colocar el fragmento en el pie de página de una SPA — la aplicación puede haberse renderizado antes de que el script se ejecute.
  • Agregar el fragmento solo a la página de inicio — la personalización funciona por página, por lo que cada plantilla o entrada de ruta necesita la etiqueta.
  • Olvidar async — el fragmento proporcionado ya lo incluye; no lo elimines.
  • Bloquear localStorage mediante herramientas de consentimiento de cookies — la ID de visitante se restablecerá en cada vista de página, rompiendo la continuidad.

Datos clave

PropiedadDetalle
Atributo del fragmentoIncluye async para carga no bloqueante
TamañoMenos de 15 KB
Tiempo de ejecuciónMenos de 15 ms antes de la pintura visual
Impacto en CLSCLS = 0 (sin desplazamiento de diseño)
AlmacenamientoUsa localStorage para la persistencia de la ID de visitante
Origen cruzadoDebe permitirse en configuraciones de múltiples dominios
Ubicación en SPADentro de <body> de index.html o el punto de entrada del framework
VerificaciónConsola, pestaña Red y verificación de ID en localStorage

Limitaciones y cuándo esta guía no aplica

Esta guía cubre solo la inserción del fragmento en el lado del cliente. Los frameworks de renderizado en el servidor que transmiten HTML antes de que se cierre <head> pueden necesitar que el fragmento se inyecte mediante un middleware o un helper de plantilla en lugar de un archivo estático. Si usas una CSP estricta que no permite scripts en línea o dominios de terceros, debes agregar el origen de SeaText a las directivas script-src y connect-src. El fragmento no reemplaza las herramientas de análisis o gestores de etiquetas existentes; se ejecuta junto a ellos.

Preguntas frecuentes

¿Qué sucede después de pegar el fragmento?

El navegador obtiene el script de SeaText de forma asíncrona. Crea una ID de visitante en localStorage y luego activa cualquier agente que hayas activado en el panel de control.

¿Cómo puedo confirmar que los agentes están activos?

Abre el panel de control de SeaText, ve al panel de Agentes y asegúrate de que el interruptor esté en verde. En la consola del navegador verás mensajes como “SeaText agent Google Ads initialized”.

Mi sitio usa una política de seguridad de contenido estricta. ¿Funcionará el fragmento?

Solo si agregas el dominio del script de SeaText a script-src y su dominio de API a connect-src. Sin estas autorizaciones, el script será bloqueado y verás errores de CSP en la consola.

¿Funciona el fragmento con Google Tag Manager u otros gestores de etiquetas?

Sí. Crea una etiqueta HTML personalizada con el fragmento y dispárala en All Pages. Colócala antes de otras etiquetas de marketing para asegurar una personalización temprana.

¿Puedo usar el mismo fragmento en múltiples dominios?

Sí, pero cada dominio debe estar listado en la configuración de tu proyecto de SeaText. El fragmento se cargará de forma cruzada siempre que la CSP lo permita.

¿Qué pasa si localStorage está bloqueado en la navegación privada?

El script se cargará, pero no podrá almacenar la ID de visitante. La personalización se restablecerá en cada vista de página. Considera usar sessionStorage como respaldo o deshabilitar los agentes para esos usuarios.

¿El fragmento aumentará el tiempo de carga de la página?

No. Tiene menos de 15 KB, se carga de forma asíncrona y se ejecuta en menos de 15 ms antes de la pintura, manteniendo saludables las Core Web Vitals.

¿Hay un fragmento separado para cada agente?

No. Un fragmento universal carga la plataforma; los agentes se activan o desactivan en el panel de control.

Aprende más

Visita el sitio web para obtener más información.

Recommended Solution

Ready to Take the Next Step?

See how our verified tools and services help you put this guide into practice.