O snippet de tracking é um pequeno script assíncrono — alguns kilobytes servidos a partir de um caminho first-party em cache de edge — que identifica a organização por trás de cada sessão. Quando instalado corretamente, nunca deverá notar a sua presença. Se instalado incorretamente, passará uma semana a depurar por que razão as empresas identificadas não aparecem, antes de descobrir que o loader estava dentro de um componente dinâmico com lazy-load. Este guia ajuda-o a evitar essa semana perdida.
Três princípios antes de colar o que quer que seja
- O loader pertence ao head HTML global do site. Não ao rodapé, não a um template de página específico, nem a um componente que apenas renderiza em páginas de marketing. No head, em todas as páginas.
- O loader é assíncrono (async) por defeito. Não adicione overrides de defer/async que alterem o momento da execução; os atributos fornecidos são os que testámos.
- Instale apenas uma vez. Duas cópias do loader na mesma página não duplicam os seus dados — duplicam os pedidos e confundem a depuração.
WordPress
A instalação mais limpa no WordPress evita edições no tema. Utilize um plugin de header-scripts (qualquer um dos conhecidos serve), cole o loader no campo "scripts no head", guarde e limpe qualquer cache de página. Se não quiser um plugin, adicione um pequeno ficheiro mu-plugin que utilize o hook wp_head com prioridade 5, para que o loader apareça antes das tags de analytics. Não o cole no corpo de uma página ou post — o WordPress irá remover a tag de script por segurança.
Uma verificação específica para WordPress: se utiliza cache de página inteira (LiteSpeed, WP Rocket, W3 Total Cache), limpe a cache após a instalação. O HTML em cache anterior à instalação não conterá o loader.
Shopify
O Shopify coloca o HTML do tema em theme.liquid. No seu painel de administração Shopify, abra Loja Online → Temas → Ações → Editar código → theme.liquid, e cole o loader imediatamente antes da tag de fecho </head>. Guarde. É tudo — não é necessária qualquer app, nem scripts de checkout (o checkout está fora do âmbito da identificação ao nível da empresa de qualquer forma).
Duplique o tema primeiro
Antes de editar o theme.liquid, utilize Ações → Duplicar. Se algo correr mal, pode reverter com um clique. Este é um hábito de cinco segundos que já salvou todas as equipas Shopify a quem foi sugerido.
Webflow
Webflow → Site Settings → Custom Code → Head Code. Cole o loader. Guarde. Publique o site. O código do head aplica-se globalmente a todas as páginas, que é exatamente o que pretende. Não cole o loader num embed ao nível da página — apenas faria o tracking dessa página específica.
Google Tag Manager
O GTM funciona, com duas ressalvas. Primeiro, utilize uma tag de HTML Personalizado com o trigger definido para "Todas as Páginas" para que o loader corra em cada visualização. Segundo, defina a prioridade da tag como suficientemente alta para que seja disparada antes de outras tags de analytics que possam atrasar o payload inicial. Os utilizadores de GTM acumulam frequentemente várias tags no head; o loader é pequeno, mas a ordem de disparo das tags é importante para a identificação no primeiro pedido.
Ressalva sobre o modo de consentimento: se utiliza o GTM atrás de um banner de consentimento que apenas dispara tags de analytics após o opt-in, não coloque a identificação ao nível da empresa sob o mesmo filtro — esta não utiliza cookies nem armazena dados no dispositivo do visitante, pelo que não requer a mesma superfície de consentimento. Configure a tag para disparar imediatamente, juntamente com as suas tags estritamente necessárias.
HTML simples / stacks personalizadas
Para um site feito à mão ou uma framework não mencionada, cole o loader dentro do elemento <head> do seu template base — o ficheiro que renderiza todas as páginas. Faça o rebuild e redeploy. Para geradores de sites estáticos, o loader pertence ao ficheiro de layout global (em Next.js, trata-se de um <Script> no layout ao nível da app com strategy="afterInteractive"; no Astro, o componente <BaseHead>; no 11ty, o partial do template base). Se o adicionou como um script ao nível do componente, apenas as páginas que incluem esse componente reportarão dados.
Single-page applications — a única armadilha
Numa SPA, a visualização inicial da página é capturada pelo loader quando a página carrega pela primeira vez. As navegações subsequentes no lado do cliente não são visualizações de página automáticas do ponto de vista do browser. O nosso loader monitoriza a History API por defeito, pelo que as navegações baseadas em retroceder/avançar e pushState registam-se como novas visualizações sem qualquer código adicional. Se a sua SPA utiliza um router não standard que ignora a History API (raro, mas possível), chame a pequena função de pageview documentada na mudança de rota — são três linhas, referenciadas na documentação.
Verifique a instalação em dois minutos
A verificação não é opcional. Faça-a antes de fechar o separador onde instalou o loader; detetar uma instalação incorreta cinco minutos após a colagem é trivial, detetá-la cinco dias depois não o é.
- Abra o seu site numa janela privada/incógnita (para que assets em cache não o confundam).
- Abra o DevTools → separador Network (Rede), filtre por "l5e" ou pelo caminho do loader.
- Recarregue a página. Deverá ver um pedido para o loader e, em seguida, um pequeno beacon de identificação. Ambos devem ter o estado 200. Os cabeçalhos de resposta do loader devem incluir um cache-control com s-maxage e stale-while-revalidate.
- Navegue para uma segunda página. Deverá ver disparar mais um beacon de identificação, sem novo download do loader (este devolverá 304).
- Regresse ao dashboard da lead.box, abra o live visitor feed e confirme que a sua visita de teste aparece. Se aparecer, a instalação está concluída.
Erros comuns — a tabela a consultar primeiro
| Sintoma | Causa provável | Correção |
|---|---|---|
| Nenhuma visita ao vivo | Loader em falta no head, ou no template errado | Mova o loader para o template de head global do site |
| Visitas ao vivo apenas de uma secção | Loader num embed ao nível da página, não global | Mova para o head global / header do tema |
| Loader carrega mas sem beacon de identificação | Banner de consentimento a bloquear scripts de terceiros de forma agressiva | Configure o banner para permitir estritamente necessários; o loader não precisa de consentimento |
| Beacons duplos por visualização | Loader instalado duas vezes (tema + plugin/tag) | Remova uma das instâncias |
| Slow first paint após instalação | Loader colocado antes do CSS crítico | Confirme se o atributo async está presente; coloque após o preload do CSS crítico |
| SPA reporta apenas a primeira página | Router personalizado ignora a History API | Chame a função pageview() documentada na mudança de rota |
| HTML antigo servido sem o loader | Cache de página inteira não limpa após instalação | Limpe a cache; verifique em modo incógnito |
Nota de performance — loader em cache de edge
O loader é servido a partir de um caminho first-party com proxy para a nossa cache de edge com s-maxage=300 e stale-while-revalidate. Na prática, isto significa que o loader é obtido uma vez a cada cinco minutos por PoP de edge, sendo depois servido a partir da cache a todos os visitantes subsequentes. O peso em bytes e o impacto no bloqueio são reduzidos o suficiente para não recomendarmos camadas adicionais de lógica de carregamento.
Quando pedir ajuda
Se seguiu os passos de verificação e algo ainda não está bem, preferimos ter notícias suas aos dez minutos do que aos dez dias. Prepare três coisas: o URL do site, um screenshot do separador Network do DevTools filtrado pelo caminho do loader, e o nome da plataforma onde instalou. Isso é suficiente para diagnosticar quase todos os problemas de instalação logo na primeira resposta.
Publicado por
lead.box Team
Mais artigos
Veja o lead.box no seu próprio tráfego
Comece gratuitamente — sem cartão, sem necessidade de chamada de vendas. Ou reserve uma demonstração de 20 minutos se preferir uma visita guiada.