Experimente o Omnifox grátis 7 dias grátis. Sem cartão de crédito.
Guias

Chat em site HTML, React ou Next.js: instalar o widget em uma SPA

Como instalar um chat em HTML, React, Next.js, Vue ou Angular sem duplicar o script, com rotas no cliente, usuários identificados e modo escuro.

September 06, 2026
Chat em site HTML, React ou Next.js: instalar o widget em uma SPA
Neste artigo

    Instalar um chat em site HTML é colar uma linha antes de </body>. Instalar o mesmo chat em React ou Next.js é onde as coisas quebram: o script carrega duas vezes no modo estrito, o balão duplica ao trocar de rota, o acionador da página de preços dispara na home e o usuário logado aparece como "Visitante 4821" na caixa de entrada. Nada disso é culpa do framework; é o widget sendo tratado como se a página recarregasse a cada clique.

    Este post é para quem escreve o código: HTML estático, React e Next.js, Vue e Nuxt, Angular, os três problemas clássicos de SPA (rotas, montagem dupla, CSP), identificação de usuários logados com HMAC no backend e modo escuro automático.

    HTML estático: o caso base

    Em um site HTML, Hugo, Jekyll, Astro em modo estático ou qualquer coisa que gere páginas completas, o widget vai no fim do <body>:

    <script src="https://omnifox.io/widget/loader.js" data-widget-key="SUA_CHAVE" async></script>
    

    O atributo async já evita bloquear a renderização. Se você tem um layout base (_layout.html, baseof.html), cole ali uma vez e todas as páginas herdam. A chave sai do painel em Canais → seu canal de chat no site → Instalar, e o painel detecta os domínios onde o widget está ativo, então dá para conferir sem abrir o DevTools.

    React e Next.js: carregar uma vez, no layout

    O erro mais comum é colocar o <script> dentro de um componente de página. Em uma SPA, o componente monta e desmonta a cada navegação, e o loader é injetado de novo. O widget deve viver no layout raiz, que monta uma única vez.

    Next.js com App Router

    Use next/script com a estratégia afterInteractive no app/layout.tsx:

    import Script from "next/script";
    
    export default function RootLayout({ children }) {
      return (
        <html lang="pt-BR">
          <body>
            {children}
            <Script
              src="https://omnifox.io/widget/loader.js"
              data-widget-key={process.env.NEXT_PUBLIC_OMNIFOX_WIDGET_KEY}
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    

    afterInteractive carrega o script depois da hidratação, sem atrasar o LCP. Com Pages Router, o mesmo Script vai em pages/_app.tsx. A chave em variável de ambiente pública permite usar um canal de chat diferente para staging e produção, cada um com seu widget no painel.

    React puro (Vite, CRA)

    Sem next/script, o caminho mais simples é o index.html do projeto, que funciona como HTML estático. Se você precisa injetar por código (por exemplo, só após consentimento de cookies), faça isso em um useEffect do componente raiz com uma verificação de existência:

    useEffect(() => {
      if (document.querySelector('script[data-widget-key]')) return;
      const s = document.createElement("script");
      s.src = "https://omnifox.io/widget/loader.js";
      s.dataset.widgetKey = import.meta.env.VITE_OMNIFOX_WIDGET_KEY;
      s.async = true;
      document.body.appendChild(s);
    }, []);
    

    A verificação do querySelector é o que impede a montagem dupla no StrictMode do React 18, que executa efeitos duas vezes em desenvolvimento.

    Vue, Nuxt e Angular

    Stack Onde colocar o script Observação
    Vue (Vite) index.html, antes de </body> Igual ao HTML estático
    Nuxt 3 nuxt.config.ts → app.head.script com async: true e body: true Fica no layout raiz automaticamente
    Angular src/index.html, antes de </body> Não use innerHTML em componentes; o sanitizer remove <script>
    Astro com ilhas Layout .astro compartilhado Só uma vez, fora dos componentes de ilha
    Gatsby gatsby-ssr.js com onRenderBody e setPostBodyComponents Mantém o script após o conteúdo

    Em todos os casos a regra é a mesma: um único ponto de injeção, no nível mais alto da árvore, fora de qualquer componente que remonte.

    Os três problemas de SPA e como resolver

    1. Troca de rota sem recarga. O acionador "URL contém /precos" precisa saber que o usuário saiu da home. O widget do Omnifox escuta a navegação do cliente, então os acionadores por URL, tempo na página e scroll reagem à rota nova sem location.reload(). Se o balão da página de preços aparecer na home, confira se a condição está como "contém" ou "exata": em SPAs com query strings de filtro, "começa com" costuma ser a escolha certa.
    2. Montagem dupla. Sintomas: dois balões, dois sons de mensagem nova, evento widget_loaded disparando duas vezes no GA4. Causa: script no componente de página, StrictMode, ou o mesmo script no index.html e no useEffect. Solução: um ponto de injeção e a verificação de existência do exemplo acima.
    3. CSP. Se o site envia Content-Security-Policy, inclua https://omnifox.io em script-src e connect-src, e o mesmo domínio em img-src para avatares e anexos. Teste com o modo Content-Security-Policy-Report-Only antes de aplicar em produção; um bloqueio silencioso é o motivo número um de "o widget não aparece só em produção".

    Identificar o usuário logado com HMAC

    Em um SaaS, o valor do chat dobra quando o atendente vê quem está falando: plano, empresa, histórico. O Omnifox oferece window.Omnifox.identify com uma assinatura HMAC calculada no backend com o segredo do canal, para que ninguém consiga se passar por outro usuário alterando o JavaScript.

    No backend (Node como exemplo), gere o hash a partir do identificador do usuário:

    const crypto = require("crypto");
    const userHash = crypto
      .createHmac("sha256", process.env.OMNIFOX_CHANNEL_SECRET)
      .update(String(user.id))
      .digest("hex");
    

    No frontend, depois que o widget carregou e o usuário está autenticado:

    window.Omnifox.identify({
      user_id: "usr_18342",
      user_hash: "a91f...c03e",
    });
    

    O contato é criado ou atualizado pelo identificador externo, e a conversa no chat do site já chega ao atendente vinculada à ficha certa no CRM, com o histórico de WhatsApp e e-mail do mesmo cliente. Chame identify uma vez por sessão autenticada, no mesmo lugar onde você já inicializa analytics ou monitoramento de erros; não chame em cada troca de rota.

    Uma boa prática de segurança: o segredo do canal nunca vai para o frontend. Se o hash é calculado no cliente, a assinatura não serve para nada.

    Modo escuro, idioma e o que não precisa de código

    Três coisas que desenvolvedores tendem a implementar à mão sem necessidade:

    • Modo escuro automático. O widget tem modo claro, escuro ou automático pela preferência do sistema do visitante. Se o seu app tem um toggle próprio, deixe o widget em automático e ele acompanha prefers-color-scheme; para casos em que o tema do app difere do sistema, o CSS personalizado do widget permite ajustar cores.
    • Idioma. A interface do widget aparece em português, espanhol ou inglês conforme o idioma do navegador. A tradução da conversa entre visitante e atendente é opcional e consome créditos de IA.
    • Eventos de analytics. widget_loaded, widget_opened, conversation_started e message_sent são enviados ao dataLayer e ao gtag automaticamente, se existirem na página. Não há necessidade de instrumentar cliques no balão.

    Para o resto da equipe, que vai configurar acionadores e IA sem tocar no repositório, vale o post sobre chat ao vivo, chatbot de regras ou agente de IA.

    Checklist antes do deploy

    • Script em um único ponto (layout raiz ou index.html), com async.
    • Chave do widget em variável de ambiente, um canal para staging e outro para produção.
    • Verificação de existência se a injeção for por código.
    • CSP liberando omnifox.io em script-src, connect-src e img-src.
    • identify chamado só após autenticação, com hash gerado no servidor.
    • Teste em aba anônima: um balão, um widget_loaded, acionador da página certa reagindo à navegação.

    Perguntas frequentes

    Posso instalar o widget só em algumas rotas da SPA?

    Sim, mas o jeito recomendado é carregar o script uma vez e usar um acionador com condição de URL e ação de ocultar o widget nas rotas onde ele não deve aparecer. Montar e desmontar o script por rota causa duplicação.

    O identify funciona sem user_hash?

    O hash é a assinatura que garante que o usuário é quem diz ser. Sem ele, qualquer pessoa poderia editar o JavaScript e assumir a identidade de outro cliente; use sempre o user_hash calculado no backend com o segredo do canal.

    Como testar em localhost?

    O widget carrega em localhost normalmente. Crie um canal de chat no site separado para desenvolvimento, assim as conversas de teste não caem na caixa de entrada de produção e a detecção de domínio do painel mostra cada ambiente.

    Conclusão: uma injeção, um layout, um hash

    Um chat em site HTML, React ou Next.js dá certo quando o script mora em um único lugar, os acionadores cuidam das rotas e a identificação do usuário é assinada no servidor. O resto (tema, idioma, analytics) o widget já resolve sem código.

    Veja a página do chat no site do Omnifox, incluído em todos os planos, e crie sua conta no teste grátis de 7 dias para pegar a chave do widget e o segredo do canal.

    Pronto para testar no seu negócio?

    Reúna WhatsApp, Instagram, Messenger, e-mail e chamadas em uma só caixa de entrada e deixe a IA dar a primeira resposta. Configure hoje mesmo.

    7 dias grátis. Sem cartão de crédito.

    Comentários (0)

    Ainda não há comentários. Seja o primeiro a compartilhar.

    Deixe um comentário

    Seu email nunca é publicado. Os comentários são moderados antes de aparecer.

    Markdown suportado. HTML é removido.

    Leia mais

    Fale conosco no WhatsApp