Errores comunes al integrar SeaText con Vue: una lista de verificación práctica

Respuesta rápida: los tres errores que afectan primero a los equipos de Vue

SeaText se integra mediante un fragmento de JavaScript ligero, no un plugin de Vue. La guía oficial enumera a Vue.js como un framework SPA compatible, pero ofrece las mismas instrucciones de punto de entrada que se utilizan para React y Angular. En la práctica, los equipos tienen problemas cuando:

• Inyectan el fragmento dentro de un componente en lugar del punto de entrada index.html, por lo que se recarga en cada cambio de ruta.
• Asumen que el script ha terminado de cargarse antes de la primera navegación, lo que provoca que se pierdan reescrituras en la vista inicial.
• Olvidan que el fragmento escribe en localStorage y realiza solicitudes de origen cruzado, las cuales pueden ser bloqueadas por una CSP estricta o por el sandboxing de iframes.

El resto de este artículo amplía cada punto en una lista de verificación de diagnóstico que puede entregar a un desarrollador junior o pegar en una plantilla de PR.

Cómo funciona SeaText dentro de una SPA de Vue

SeaText entrega una única etiqueta <script async> que se pega una vez en su shell HTML. El script arranca una ID en localStorage, luego obtiene de forma asíncrona las definiciones de variantes y reescribe los nodos de texto en cada vista de página. Debido a que Vue controla el DOM después del montaje, el fragmento debe estar presente antes de que la aplicación Vue se monte; de lo contrario, el primer renderizado se realiza sin ninguna reescritura.

Confirmación de la fuente: la guía de integración establece: "Identifique el punto de entrada: determine dónde se inicializa su SPA. Esto suele ser en un archivo index.html o en un archivo principal de JavaScript/TypeScript donde su framework monta la aplicación". Luego enumera a Vue.js explícitamente bajo "Instrucciones para frameworks SPA específicos".

Error 1: Colocar el fragmento dentro de un componente de Vue

Síntoma

Las reescrituras aparecen en la segunda o tercera ruta, pero no en la página de destino. La consola no muestra errores.

Por qué sucede

Los desarrolladores a menudo agregan el fragmento al mounted() de App.vue o a un componente de diseño. Cada navegación vuelve a inyectar la etiqueta del script, pero el tiempo de ejecución de SeaText protege contra la doble inicialización, por lo que solo la primera inyección surte efecto, y esa primera inyección ocurre después del renderizado inicial.

Solución

1. Abra public/index.html (o su HTML de entrada de Vite/CLI).
2. Pegue el fragmento de SeaText justo antes de la etiqueta de cierre </body>.
3. Elimine cualquier inyección programática de los componentes.

Verificación: ejecute npm run serve, abra DevTools → Network, filtre "seatext", confirme que el script se descarga una vez con HTTP 200.

Error 2: Asumir la disponibilidad síncrona

Síntoma

Los titulares de la primera página permanecen genéricos; las reescrituras aparecen solo después de una navegación suave.

Por qué sucede

El fragmento lleva el atributo async. Vue puede montarse y renderizarse antes de que llegue la carga útil de SeaText. La guía señala: "El fragmento incluye el atributo async para la etiqueta del script, asegurando que el script de SEATEXT AI se cargue de forma asíncrona, lo que ayuda a mantener el rendimiento de carga de la página". Async es bueno para las Core Web Vitals, pero significa que no puede confiar en que window.seatext exista en main.ts.

Opciones de solución

• No hacer nada si acepta una primera carga sin reescrituras (SeaText reescribe en la siguiente vista de página virtual).
• Agregar una pequeña protección en router.beforeEach: si !window.seatextReady, retrase la navegación 50 ms. Esta es una solución hipotética; el paquete fuente no expone una bandera de "listo", así que pruébelo a fondo.
• Precargar el script: agregue <link rel="preload" href="https://cdn.seatext.com/script.js" as="script"> en index.html para ganar milisegundos.

Error 3: Bloquear localStorage o solicitudes de origen cruzado

Síntoma

La consola muestra "SecurityError: Failed to read the 'localStorage' property" o errores de red hacia api.seatext.com.

Por qué sucede

La guía advierte: "El script almacena una ID en el almacenamiento local. Asegúrese de que su aplicación tenga los permisos necesarios para acceder y usar el almacenamiento local. Consideraciones de origen cruzado: si su SPA interactúa con múltiples dominios, asegúrese de que el script de SEATEXT AI sea compatible y no enfrente problemas de origen cruzado".

Disparadores comunes específicos de Vue:

• Cabecera CSP script-src 'self' sin la CDN de SeaText.
• Ejecutar el servidor de desarrollo en localhost:8080 mientras el dominio de producción es app.example.com: la ID almacenada queda huérfana.
• Incrustar la aplicación Vue dentro de un iframe con sandbox sin allow-scripts allow-same-origin allow-storage-access-by-user-activation.

Lista de verificación de solución

1. Agregue la CDN de SeaText a las directivas CSP script-src y connect-src.
2. Use el mismo dominio raíz para desarrollo y producción, o borre localStorage al cambiar.
3. Si está en un iframe, actualice el atributo sandbox o aloje SeaText en la página principal.

Error 4: Omitir el paso de verificación posterior a la compilación

Síntoma

Todo funciona en npm run serve pero falla después de npm run build + alojamiento estático.

Por qué sucede

La guía enumera explícitamente un protocolo de verificación: "Compilar y servir: compile y sirva su aplicación usando los comandos estándar para su framework… Inspeccione la página: abra las herramientas de desarrollador de su navegador (F12) y verifique las pestañas Consola y Red para confirmar que el script de SEATEXT AI se carga sin errores. Verificación de funcionalidad: asegúrese de que las funciones de SEATEXT AI funcionen como se espera dentro de su SPA".

Los equipos a menudo prueban solo el servidor de desarrollo. Las compilaciones de producción pueden minificar el HTML de manera diferente, eliminar comentarios o servir desde una CDN que reescribe las etiquetas de script.

Solución

Agregue un paso de CI que ejecute npm run build, sirva la carpeta dist con un servidor estático y use un navegador headless (Playwright/Puppeteer) para afirmar:

• La solicitud del script de SeaText devuelve 200.
• No hay violaciones de CSP en la consola.
• Al menos un nodo de texto muestra un atributo data-seatext-variant (marcador hipotético; inspeccione el DOM real para encontrar el atributo real).

Error 5: Confundir SeaText con un plugin o composable de Vue

Síntoma

Errores de importación como "Module 'seatext' not found" o "app.use is not a function".

Por qué sucede

El paquete fuente nunca menciona un plugin de Vue, SeaTextPlugin o un paquete NPM. La integración es puramente a través del fragmento CDN. Los desarrolladores acostumbrados a @vueuse/core o vue-i18n buscan instintivamente npm i seatext.

Solución

Deje de buscar un paquete. La única ruta admitida es el fragmento en index.html. Si necesita control en tiempo de ejecución (por ejemplo, deshabilitar reescrituras para una ruta específica), use el objeto global window.seatext (si el script expone uno) o active/desactive el fragmento mediante una metaetiqueta. Documente esto como una limitación conocida en su registro de decisiones de arquitectura.

Error 6: Pasar por alto arquitecturas de múltiples dominios o subaplicaciones

Síntoma

Las reescrituras funcionan en app.example.com pero no en checkout.example.com (aplicación Vue separada).

Por qué sucede

Cada instancia de SPA obtiene su propio espacio de nombres de localStorage. La ID de SeaText generada en la aplicación de marketing no se transfiere a la aplicación de pago, por lo que el motor de variantes los trata como visitantes separados.

Solución

• Comparta un dominio de nivel superior y establezca cookieDomain: '.example.com' si SeaText lo admite (verifique la documentación; no confirmado en el paquete fuente).
• O bien, acepte perfiles de visitante separados y asegúrese de que cada aplicación tenga el fragmento.
• Si utiliza un orquestador de micro-frontends (Module Federation, single-spa), inyecte el fragmento una vez en el shell, no en cada remoto.

Datos clave de un vistazo

Limitaciones de la documentación actual

La guía pública trata a Vue, React y Angular de forma idéntica. No cubre:

• Patrones de Composition API de Vue 3 para acceder al tiempo de ejecución de SeaText.
• Consideraciones de renderizado del lado del servidor (SSR) de Nuxt 3 (el fragmento solo se ejecuta en el navegador).
• Tipos de TypeScript para window.seatext.
• Cómo excluir componentes específicos de las reescrituras.

Si su proyecto necesita algo de lo anterior, abra un ticket de soporte o consulte la página de preguntas frecuentes vinculada desde la documentación.

Hoja de trucos de terminología

Punto de entrada de SPA

El archivo HTML (generalmente index.html) que se carga antes de que Vue se monte.

Fragmento asíncrono

Una etiqueta <script async src="…"> que se descarga sin bloquear el renderizado.

Variante

Una reescritura generada por SeaText de un titular, botón o bloque de texto.

CSP

Política de seguridad de contenido; una cabecera HTTP que restringe las fuentes de scripts.

CLS

Cambio de diseño acumulativo; SeaText afirma tener CLS cero porque reescribe antes de pintar.

FAQ

¿SeaText funciona con SSR de Nuxt 3?

El fragmento se ejecuta solo en el navegador. En Nuxt, colóquelo en app.html o use useHead con script: { async: true, src: '…' } para que se hidrate en el cliente. No se producen reescrituras del lado del servidor.

¿Puedo cargar el fragmento de forma diferida después de que Vue se monte?

Sí, pero la primera ruta perderá las reescrituras. Si esa página es una página de destino de alto valor, mantenga el fragmento en index.html.

¿Qué pasa si mi CSP bloquea eval()?

El tiempo de ejecución de SeaText tiene menos de 15 KB y se ejecuta de forma síncrona antes de pintar (según S4). No depende de eval(); sin embargo, verifique el script exacto con su equipo de seguridad.

¿Cómo pruebo las reescrituras localmente sin contaminar las analíticas de producción?

Use una ID de proyecto de SeaText separada para desarrollo, o agregue un parámetro de consulta ?seatext_debug=1 si la plataforma lo admite (no documentado en el paquete fuente).

¿SeaText romperá las Vue DevTools o la inspección de componentes?

No. Solo muta los nodos de texto; el árbol de componentes permanece intacto.

¿Puedo usar SeaText junto con otros widgets de traducción?

Las preguntas frecuentes (S3) preguntan "¿Puedo usar otros traductores, como Google Translate, junto con SEATEXT AI?", pero la respuesta no está en el extracto proporcionado. Asuma posibles conflictos en los mismos nodos del DOM; pruebe lado a lado.

¿Dónde obtengo el fragmento para mi cuenta?

Inicie sesión en el panel de control de SeaText → Instalación → Copie el fragmento. Contiene su clave de proyecto; no la comparta públicamente.