¿Puedo usar SeaText AI sin configurar el ámbito (scope) para mi SPA?

No, no puedes usar SeaText AI de forma fiable sin configurar el ámbito para tu SPA.

Sin un ámbito definido, la IA no puede detectar los cambios de contenido que ocurren cuando la SPA actualiza la vista mediante el enrutamiento del lado del cliente, por lo que las optimizaciones podrían perderse o aplicarse a contenido obsoleto.

Por qué el ámbito es obligatorio para las SPA con enrutamiento del lado del cliente

En una aplicación de una sola página (SPA), el navegador no recarga la página cuando el usuario navega. En su lugar, el framework intercambia componentes dentro de un contenedor raíz mientras la URL cambia. SeaText AI necesita saber qué contenedor contiene el contenido dinámico para poder reevaluar la página después de cada navegación. La documentación de SeaText incluye una sección dedicada "Cómo configurar / Ámbito de la IA" para este propósito. Si se omite el ámbito, la IA solo ve la renderización inicial y nunca procesa las vistas posteriores.

Cómo afecta el enrutamiento del lado del cliente a la detección de contenido

Los enrutadores del lado del cliente (React Router, Vue Router, Angular Router) actualizan el DOM reemplazando el HTML interno de un elemento montado. El fragmento (snippet) de SeaText se carga una vez al cargar la página inicialmente. Sin un selector de ámbito, la IA no tiene referencia al elemento que cambia. La guía de integración documentada para SPA explica que debes identificar el punto de entrada, añadir el fragmento y luego definir el ámbito en el panel de control para que la IA pueda monitorear la región correcta.

Cómo elegir un contenedor raíz fiable en React, Vue y Angular

Cada framework monta la aplicación en un nodo DOM específico. En React, la convención es un div con id="root" o id="app". En Vue, el punto de montaje suele ser #app. Angular utiliza app-root como selector de componente predeterminado. La guía de integración de SeaText recomienda colocar el fragmento en el body del punto de entrada (normalmente index.html) y luego configurar el ámbito para que coincida con el elemento raíz del framework. Un selector estable como #root, #app o app-root funciona bien porque persiste a través de los cambios de ruta.

Si tu proyecto utiliza un contenedor personalizado o múltiples nodos raíz, elige el elemento más externo que envuelva la salida del enrutador. Evita selectores que coincidan con elementos añadidos o eliminados durante la navegación, como etiquetas de componentes específicas de la ruta.

Configuración del ámbito paso a paso mediante el panel de control

1. Identifica el punto de entrada de tu SPA (normalmente index.html o el archivo principal de JavaScript/TypeScript donde el framework monta la aplicación).
2. Inserta el fragmento de SeaText AI dentro de la etiqueta body de ese punto de entrada.
3. Compila y sirve la aplicación usando los comandos estándar de tu framework (por ejemplo, npm start, npm run serve o ng serve).
4. Abre el panel de control de SeaText y navega a la sección "Cómo configurar / Ámbito de la IA".
5. Define el ámbito introduciendo un selector CSS o una expresión de JavaScript que coincida con el contenedor donde tu SPA renderiza nuevas vistas (por ejemplo, #root para React, #app para Vue o app-root para Angular).
6. Guarda la configuración y recarga la página.
7. Práctica recomendada: Abre las herramientas de desarrollo del navegador (F12), ve a las pestañas Consola y Red, y verifica que el script de SeaText se cargue sin errores. Busca cualquier mensaje de registro relacionado con SeaText que confirme que el elemento de ámbito está siendo vigilado.

Síntomas cuando el ámbito falta o está mal configurado

• La IA sigue monitoreando solo la carga inicial de la página; los cambios de ruta posteriores son invisibles para el motor de optimización.
• Los titulares, ofertas o traducciones personalizados aparecen en la vista incorrecta o no aparecen en absoluto.
• Los informes de rendimiento no muestran mejoras porque la IA nunca ve el contenido actualizado.
• Si el selector es demasiado amplio (por ejemplo, body), la IA puede procesar elementos de la interfaz de usuario no relacionados, como encabezados o pies de página en cada navegación, desperdiciando presupuesto de procesamiento.
• Si el selector es demasiado estrecho (por ejemplo, un componente que se desmonta), la IA pierde su referencia y deja de actualizarse.

Comportamiento de reserva cuando el ámbito no está definido

Si dejas el ámbito sin definir, SeaText AI se cargará y ejecutará de todos modos. Actuará sobre los elementos del DOM presentes en el momento en que el script se ejecuta por primera vez. En una SPA típica, se renderiza el shell inicial y luego el framework intercambia componentes dentro de un contenedor. Debido a que la IA no reevalúa el contenedor después de cada navegación, cualquier titular, oferta o CTA que deba cambiar con la ruta permanecerá como estaba en la primera carga. Este comportamiento está documentado en la guía de integración de SPA: el fragmento se carga de forma asíncrona, utiliza almacenamiento local para un ID y maneja consideraciones de origen cruzado, pero sin un ámbito no puede adaptarse a los cambios de ruta del lado del cliente.

Perspectiva experta: Por qué el ámbito no es negociable para las SPA

"En cada integración de SPA que he visto, omitir el paso del ámbito es la razón número uno por la que la personalización falla. El fragmento de la IA se carga una vez, pero la aplicación reescribe el DOM muchas veces. Sin un selector estable que apunte a la salida del enrutador, la IA es ciega a esas reescrituras. Siempre le digo a los equipos: elijan el elemento raíz en el que se monta su framework (#root, #app, app-root) y bloquéenlo en el panel de control. Luego hagan una prueba rápida: naveguen entre dos rutas y verifiquen que la IA actualice el titular. Si no lo hace, el selector es incorrecto. Esa comprobación de cinco minutos ahorra semanas de preguntarse por qué las conversiones no aumentaron."

Guía de solución de problemas

1. Confirma que el fragmento esté presente en el index.html compilado (ver código fuente de la página).
2. Verifica que el selector de ámbito en el panel de control coincida con un elemento que exista en cada ruta y envuelva el contenido dinámico.
3. Abre la consola de las herramientas de desarrollo, navega entre rutas y observa si hay solicitudes de red de SeaText o entradas de registro que indiquen un reanálisis del contenido.
4. Si no aparece ninguna actividad, verifica dos veces que el selector no esté bloqueado por un shadow DOM o un ID generado dinámicamente que cambie en cada renderizado.
5. Prueba primero con un selector CSS simple (por ejemplo, #root). Si eso funciona, puedes refinarlo a un contenedor más específico si es necesario.
6. Asegúrate de que la aplicación tenga permiso para usar localStorage (requerido por el fragmento) y que ninguna política de origen cruzado bloquee el script de SeaText.

Limitaciones y cuándo puede no ser necesario el ámbito

Esta guía se aplica a las SPA estándar con enrutamiento del lado del cliente que cambian la vista sin una recarga completa de la página. Si tu aplicación utiliza renderizado del lado del servidor para cada ruta (por ejemplo, Next.js con getServerSideProps o navegación tradicional de varias páginas), es posible que el paso del ámbito no sea necesario porque cada navegación activa una carga completa de la página y la IA se ejecuta automáticamente en el nuevo HTML. Además, si solo necesitas que SeaText AI se ejecute en la página de destino inicial y nunca se actualice después de la navegación, podrías dejar el ámbito sin definir, pero te perderías cualquier personalización o traducción dinámica en las vistas posteriores.

Glosario de terminología

Ámbito (Scope)

El selector CSS o la expresión de JavaScript que le indica a SeaText AI qué parte de la página debe vigilar para detectar actualizaciones.

Punto de entrada (Entry point)

El archivo donde se ejecuta el código de arranque de la SPA, generalmente index.html o el archivo JS/TS principal.

Carga asíncrona (Asynchronous loading)

Un método de carga de scripts que no bloquea la renderización de la página; el fragmento de SeaText incluye el atributo async.

Enrutamiento del lado del cliente (Client-side routing)

Navegación manejada por JavaScript sin una recarga completa de la página, típica en SPA de React, Vue y Angular.

Contenedor raíz (Root container)

El elemento DOM donde el framework monta la aplicación y donde el enrutador intercambia las vistas.

Preguntas frecuentes

¿Qué pasa si uso un framework que no expone un elemento raíz?

Aún puedes definir el ámbito seleccionando un contenedor estable que envuelva la salida enrutada, como un div con una clase o ID conocido. Si no existe tal contenedor, considera añadir uno únicamente con el propósito de definir el ámbito de SeaText AI.

¿Puedo cambiar el ámbito después de la carga inicial?

Sí. Actualizar el ámbito en el panel de control de SeaText hará que la IA comience a monitorear el nuevo selector en la siguiente vista de página. Para aplicaciones de una sola página, se requiere una recarga completa para que el cambio surta efecto.

¿El ámbito afecta la facturación o los límites de uso?

No. El ámbito es solo una configuración; no influye en la cantidad de agentes de IA que puedes activar ni en los límites de tráfico de tu plan.

¿Qué debo hacer si no veo cambios después de configurar el ámbito?

Abre la consola del navegador y busca los registros de SeaText AI. Verifica que el selector coincida con un elemento que realmente se actualice cuando navegas. Si el selector es demasiado amplio o demasiado estrecho, ajústalo y recarga.

¿Es necesario el ámbito para las páginas renderizadas en el servidor?

Generalmente no. Cuando cada navegación activa una recarga completa de la página, la IA se ejecuta automáticamente en el nuevo HTML, por lo que un ámbito explícito es innecesario.