Posso usar o SeaText AI sem configurar o escopo para minha SPA?

Não, você não pode usar o SeaText AI de forma confiável sem configurar o escopo para sua SPA.

Sem um escopo definido, a IA não consegue detectar alterações de conteúdo que acontecem quando a SPA atualiza a visualização via roteamento do lado do cliente, portanto, as otimizações podem ser perdidas ou aplicadas a conteúdo obsoleto.

Por que o escopo é obrigatório para SPAs com roteamento do lado do cliente

Em uma aplicação de página única (SPA), o navegador não recarrega a página quando o usuário navega. Em vez disso, o framework troca componentes dentro de um contêiner raiz enquanto a URL muda. O SeaText AI precisa saber qual contêiner contém o conteúdo dinâmico para que possa reavaliar a página após cada navegação. A documentação do SeaText inclui uma seção dedicada "Como configurar / Escopo da IA" para esse fim. Se o escopo for omitido, a IA vê apenas a renderização inicial e nunca processa as visualizações subsequentes.

Como o roteamento do lado do cliente afeta a detecção de conteúdo

Roteadores do lado do cliente (React Router, Vue Router, Angular Router) atualizam o DOM substituindo o HTML interno de um elemento montado. O snippet do SeaText carrega uma vez no carregamento inicial da página. Sem um seletor de escopo, a IA não tem referência ao elemento que muda. O guia de integração documentado para SPAs explica que você deve identificar o ponto de entrada, adicionar o snippet e, em seguida, definir o escopo no painel para que a IA possa monitorar a região correta.

Escolhendo um contêiner raiz confiável em React, Vue e Angular

Cada framework monta a aplicação em um nó DOM específico. No React, a convenção é uma div com id="root" ou id="app". No Vue, o ponto de montagem é geralmente #app. O Angular usa app-root como o seletor de componente padrão. O guia de integração do SeaText recomenda colocar o snippet no body do ponto de entrada (geralmente index.html) e, em seguida, configurar o escopo para corresponder ao elemento raiz do framework. Um seletor estável como #root, #app ou app-root funciona bem porque persiste durante as mudanças de rota.

Se o seu projeto usa um wrapper personalizado ou vários nós raiz, escolha o elemento mais externo que envolve a saída do roteador. Evite seletores que correspondam a elementos adicionados ou removidos durante a navegação, como tags de componentes específicas de rota.

Configuração de escopo passo a passo usando o painel

1. Identifique o ponto de entrada da sua SPA (normalmente index.html ou o arquivo principal JavaScript/TypeScript onde o framework monta a aplicação).
2. Insira o snippet do SeaText AI dentro da tag body desse ponto de entrada.
3. Compile e execute a aplicação usando os comandos padrão do seu framework (por exemplo, npm start, npm run serve ou ng serve).
4. Abra o painel do SeaText e navegue até a seção "Como configurar / Escopo da IA".
5. Defina o escopo inserindo um seletor CSS ou expressão JavaScript que corresponda ao contêiner onde sua SPA renderiza novas visualizações (por exemplo, #root para React, #app para Vue ou app-root para Angular).
6. Salve a configuração e recarregue a página.
7. Prática recomendada: Abra as Ferramentas do Desenvolvedor do navegador (F12), vá para as guias Console e Rede e verifique se o script do SeaText carrega sem erros. Procure por quaisquer mensagens de log relacionadas ao SeaText que confirmem que o elemento de escopo está sendo monitorado.

Sintomas quando o escopo está ausente ou mal configurado

• A IA continua monitorando apenas o carregamento inicial da página; mudanças de rota posteriores são invisíveis para o mecanismo de otimização.
• Manchetes, ofertas ou traduções personalizadas aparecem na visualização errada ou não aparecem.
• Relatórios de desempenho não mostram melhorias porque a IA nunca vê o conteúdo atualizado.
• Se o seletor for muito amplo (por exemplo, body), a IA pode processar elementos de interface não relacionados, como cabeçalhos ou rodapés em cada navegação, desperdiçando o orçamento de processamento.
• Se o seletor for muito restrito (por exemplo, um componente que é desmontado), a IA perde sua referência e para de atualizar.

Comportamento de fallback quando o escopo não está definido

Se você deixar o escopo indefinido, o SeaText AI ainda carregará e será executado. Ele agirá sobre os elementos DOM presentes no momento em que o script é executado pela primeira vez. Em uma SPA típica, o shell inicial é renderizado e, em seguida, o framework troca os componentes dentro de um contêiner. Como a IA não reavalia o contêiner após cada navegação, qualquer manchete, oferta ou CTA que deveria mudar com a rota permanece como estava no primeiro carregamento. Esse comportamento está documentado no guia de integração de SPA: o snippet carrega de forma assíncrona, usa armazenamento local para um ID e lida com considerações de origem cruzada, mas sem um escopo, ele não consegue se adaptar às mudanças de rota do lado do cliente.

Perspectiva do especialista: Por que o escopo é inegociável para SPAs

"Em todas as integrações de SPA que vi, pular a etapa de escopo é a razão número um pela qual a personalização falha. O snippet da IA carrega uma vez, mas a aplicação reescreve o DOM muitas vezes. Sem um seletor estável apontando para a saída do roteador, a IA fica cega a essas reescritas. Eu sempre digo às equipes: escolham o elemento raiz no qual seu framework é montado — #root, #app, app-root — e travem-no no painel. Em seguida, faça um teste rápido: navegue entre duas rotas e verifique se a IA atualiza a manchete. Se não atualizar, o seletor está errado. Essa verificação de cinco minutos economiza semanas de dúvidas sobre por que as conversões não aumentaram."

Passo a passo para solução de problemas

1. Confirme se o snippet está presente no index.html compilado (veja o código-fonte da página).
2. Verifique se o seletor de escopo no painel corresponde a um elemento que existe em todas as rotas e envolve o conteúdo dinâmico.
3. Abra o Console das Ferramentas do Desenvolvedor, navegue entre as rotas e observe as solicitações de rede do SeaText ou entradas de log indicando a reanálise de conteúdo.
4. Se nenhuma atividade aparecer, verifique novamente se o seletor não está bloqueado por um shadow DOM ou um ID gerado dinamicamente que muda a cada renderização.
5. Teste primeiro com um seletor CSS simples (por exemplo, #root). Se funcionar, você pode refinar para um contêiner mais específico, se necessário.
6. Certifique-se de que a aplicação tenha permissão para usar localStorage (exigido pelo snippet) e que nenhuma política de origem cruzada bloqueie o script do SeaText.

Limitações e quando o escopo pode não ser necessário

Esta orientação aplica-se a SPAs padrão com roteamento do lado do cliente que alteram a visualização sem um recarregamento completo da página. Se a sua aplicação usa renderização do lado do servidor para cada rota (por exemplo, Next.js com getServerSideProps ou navegação tradicional de várias páginas), a etapa de escopo pode não ser necessária porque cada navegação aciona um carregamento completo da página e a IA é executada no novo HTML automaticamente. Além disso, se você precisar apenas que o SeaText AI seja executado na página de destino inicial e nunca seja atualizado após a navegação, você pode deixar o escopo indefinido, mas perderia qualquer personalização ou tradução dinâmica em visualizações subsequentes.

Glossário de terminologia

Escopo

O seletor CSS ou expressão JavaScript que informa ao SeaText AI qual parte da página deve ser monitorada em busca de atualizações.

Ponto de entrada

O arquivo onde o código de inicialização da SPA é executado, geralmente index.html ou o arquivo JS/TS principal.

Carregamento assíncrono

Um método de carregamento de script que não bloqueia a renderização da página; o snippet do SeaText inclui o atributo async.

Roteamento do lado do cliente

Navegação gerenciada por JavaScript sem um recarregamento completo da página, comum em SPAs React, Vue e Angular.

Contêiner raiz

O elemento DOM onde o framework monta a aplicação e onde o roteador troca as visualizações.

Perguntas frequentes

E se eu usar um framework que não expõe um elemento raiz?

Você ainda pode definir o escopo selecionando um contêiner estável que envolva a saída roteada, como uma div com uma classe ou ID conhecido. Se esse contêiner não existir, considere adicionar um apenas para fins de definição de escopo do SeaText AI.

Posso alterar o escopo após o carregamento inicial?

Sim. Atualizar o escopo no painel do SeaText fará com que a IA comece a monitorar o novo seletor na próxima visualização de página. Para aplicações de página única, é necessário um recarregamento completo para que a alteração entre em vigor.

O escopo afeta o faturamento ou os limites de uso?

Não. O escopo é apenas uma configuração; ele não influencia o número de agentes de IA que você pode ativar ou os limites de tráfego do seu plano.

O que devo fazer se não vir alterações após definir o escopo?

Abra o console do navegador e procure pelos logs do SeaText AI. Verifique se o seletor corresponde a um elemento que realmente é atualizado quando você navega. Se o seletor for muito amplo ou muito restrito, ajuste-o e recarregue.

O escopo é necessário para páginas renderizadas no lado do servidor?

Geralmente não. Quando cada navegação aciona um recarregamento completo da página, a IA é executada no novo HTML automaticamente, portanto, um escopo explícito é desnecessário.