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.
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
- 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 semlocation.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. - Montagem dupla. Sintomas: dois balões, dois sons de mensagem nova, evento
widget_loadeddisparando duas vezes no GA4. Causa: script no componente de página,StrictMode, ou o mesmo script noindex.htmle nouseEffect. Solução: um ponto de injeção e a verificação de existência do exemplo acima. - CSP. Se o site envia
Content-Security-Policy, incluahttps://omnifox.ioemscript-srceconnect-src, e o mesmo domínio emimg-srcpara avatares e anexos. Teste com o modoContent-Security-Policy-Report-Onlyantes 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_startedemessage_sentsão enviados aodataLayere aogtagautomaticamente, 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), comasync. - 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.ioemscript-src,connect-srceimg-src. identifychamado 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.
Leia mais
-

CRM para WhatsApp: como pode ajudar o meu negócio
-

O melhor chat para equipes de trabalho em 2026
-

As melhores ferramentas para integrar seu CRM com WhatsApp
-

Por que o app WhatsApp Business fica pequeno ao crescer
-

Notificacoes automaticas para clientes no Telegram: guia pratico
-

Como conectar o Calendly à sua plataforma de mensagens
-

Como unificar todos os seus canais de mensagens em um so lugar
-

O WhatsApp é da empresa, não do vendedor: como recuperar o controle
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.