Código de rastreamento HubSpot: como saber se funciona?

O material disponível sobre o código de rastreamento da HubSpot quase sempre termina na mesma frase: cole antes do fechamento da tag body. E aí acaba.

Só que colar não é a parte difícil, mas na semana seguinte, quando o relatório de tráfego está vazio e a conversa entre marketing e tecnologia vira uma troca de "está instalado sim" contra "então por que não aparece nada".

Isso é problema de verificação, não de instalação.

E tem solução documentada. A HubSpot publica cinco métodos de validação, e um deles dá resposta definitiva em menos de um minuto, direto no navegador, sem acesso ao servidor. É esse método que transforma o gestor de marketing em auditor do próprio projeto.

O que o código de rastreamento HubSpot faz no seu site?

O código de rastreamento é um script único por conta que faz três coisas: monitora o tráfego do site, reconhece quando um formulário é submetido e habilita ferramentas de conversa como o chat ao vivo. A instalação manual é necessária apenas em sites externos, e o recurso está disponível em todos os produtos e planos.

Legenda: o snippet na página é só metade do trabalho; a outra metade é provar que ele disparou.

Vale olhar cada função pelo avesso, pelo que deixa de existir sem o código.

Sem rastreamento, não há relatório de origem de tráfego. Os contatos continuam chegando, mas sem saber se vieram de busca orgânica, de mídia paga ou de e-mail, e a leitura de desempenho de marketing de conteúdo se torna inviável.

Na ausência de rastreamento, o formulário ainda cria o contato, mas a submissão perde o contexto. O histórico de páginas visitadas antes da conversão não existe, e é esse dado que separa um pedido genérico de informação de alguém que passou vinte minutos na página de um curso.

Quem trabalha captura de leads por formulários da HubSpot em operação de captação de alunos conhece a diferença que esse histórico de navegação faz na abordagem comercial.

E sem rastreamento o chat não aparece. As ferramentas de conversa, incluindo chatbots configurados na plataforma, dependem do mesmo script para carregar em sites externos.

Um detalhe que confunde muita gente: o código é único por conta, não por site. O mesmo snippet vai em todos os domínios e subdomínios que você quiser rastrear, e o que identifica a origem do dado é o número da conta embutido nele.

Onde encontrar o código de rastreamento HubSpot e o Hub ID?

O caminho é o ícone de configurações no canto superior direito, depois Tracking & Analytics > Tracking code na barra lateral. O snippet aparece na seção Embed code, com botão de cópia. Em contas de Marketing Starter e de ferramentas gratuitas, o item aparece direto como Tracking Code na sidebar.

Copie pelo botão, nunca selecionando o texto com o mouse. Seleção manual é uma origem banal de código quebrado: um caractere fora, uma quebra de linha que o editor do site leu como fim de tag.

Sobre o Hub ID, ele está dentro do próprio snippet: o script aponta para um arquivo cujo nome é o número da sua conta seguido de .js, no formato [Hub ID].js. O mesmo número aparece na barra de endereço do navegador enquanto você está logado no portal.

Guarde esse número, porque ele é a chave de todos os testes que vêm depois. É o que distingue "tem um código da HubSpot instalado" de "tem o código da minha conta instalado", distinção frequente em sites que já passaram por outro portal ou por outra agência.

Como instalar o código de rastreamento HubSpot em site externo?

A regra é colar o snippet imediatamente antes do fechamento da tag body, em todas as páginas do site.

Em sites com estrutura de templates, significa editar um único arquivo de rodapé compartilhado, de modo que o código carregue em qualquer URL do domínio.

Em WordPress, existem três caminhos com riscos diferentes.

O primeiro é editar o arquivo de rodapé do tema. Funciona, com uma ressalva: se a edição for feita no tema principal em vez de um tema filho, a próxima atualização apaga o código. É o motivo mais comum de rastreamento que funcionava e parou meses depois, sem ninguém ter mexido em nada.

O segundo é usar um plugin de injeção de scripts, ou o recurso equivalente que muitos temas oferecem para inserir código no rodapé. É o caminho mais seguro para quem não quer tocar em arquivo de tema, e sobrevive a atualizações.

A HubSpot também mantém um plugin oficial para WordPress, que instala o rastreamento sem edição manual de código.

O terceiro é distribuir o snippet por um gerenciador de tags. Cria uma dependência a mais: se a tag for pausada, o rastreamento cai junto. E o erro mais comum aqui é ninguém documentar essa decisão, com o time gastando uma tarde procurando o código no tema.

Escolhido o caminho, três cuidados evitam retrabalho:

• Cubra todos os templates. Home, páginas internas, blog, páginas de curso, busca. O site da instituição de ensino tem mais templates do que o inventário informal sugere.
• Instale uma vez só. Código duplicado na mesma página gera comportamento inconsistente e atrapalha o diagnóstico.
• Limpe o cache depois. Plugin de cache e CDN continuam entregando a versão anterior da página, e você vai testar o HTML antigo achando que a instalação falhou.

Preciso instalar o código de rastreamento em páginas da HubSpot?

Não. Em páginas de site, landing pages e posts de blog hospedados na própria HubSpot, o código é incluído automaticamente. A instalação manual existe exclusivamente para conteúdo que vive fora da plataforma, como um site em WordPress ou em outro sistema de terceiros.

Isso importa no cenário híbrido, que é o mais comum: site institucional em uma plataforma, landing pages de campanha na HubSpot. O snippet vai apenas no site institucional, e tentar adicioná-lo às landing pages só cria duplicidade.

O ponto de atenção é a continuidade da jornada. Quando o visitante navega do site externo para uma landing page da HubSpot, o rastreamento reconhece a mesma pessoa porque o cookie foi implantado no primeiro contato.

Sem o código no site externo, essa parte da jornada fica invisível e a landing page aparece no relatório como se fosse o início de tudo.

Quais são as 5 formas de validar o código de rastreamento HubSpot?

A HubSpot documenta cinco métodos de verificação: a ferramenta automática dentro das configurações, a inspeção do código-fonte, duas checagens diferentes na aba de rede do navegador e a conferência de novos page views nos relatórios de tráfego. Eles não são equivalentes, porque provam coisas distintas.

Essa é a distinção que a maioria dos tutoriais perde: ver o script no código-fonte prova que ele está na página, não que carregou nem que enviou dado para a HubSpot.

Veja o que cada método confirma:

Tabela: Os cinco métodos constam da documentação oficial; a ordem acima vai do mais indireto ao mais conclusivo.

Se você só puder fazer um teste, faça o quarto.

A requisição __ptq.gif com status 200 OK é o que confirma o disparo. Ela é a chamada que leva o registro de visualização para a HubSpot, então a presença dela na aba de rede significa que o ciclo inteiro se completou: script carregado, cookie permitido, evento enviado, servidor respondeu.

O caminho não exige conhecimento de código. Abra a página e as ferramentas de desenvolvedor com F12, vá para a aba Network, recarregue a página e digite __ptq no campo de filtro. Se a linha aparecer com 200, está funcionando. Se não aparecer nada, não está.

Na mesma aba, vale conferir dois domínios que a documentação diferencia: js.hs-scripts.com é o carregador do script e js.hs-analytics.net é a parte de rastreamento. Ver o primeiro sem o segundo indica que o carregamento começou, mas o rastreamento não subiu, o que aponta para bloqueio no navegador ou consentimento pendente.

Uma auditoria completa é necessária, que envolve: ferramenta automática para ter registro por e-mail, Hub ID conferido no código-fonte, __ptq.gif com 200 na aba de rede e, horas depois, o page view no relatório. Nada disso depende de acesso ao servidor nem de permissão do desenvolvedor, e tudo produz evidência anexável em um chamado.

Por que a HubSpot não está registrando visitas no site?

Quando a HubSpot não registra visitas, a causa quase sempre está em uma de seis frentes: Hub ID de outra conta, código ausente em parte dos templates, cache entregando a página antiga, consentimento pendente no banner de cookies, bloqueio no navegador de quem testa ou expectativa errada sobre o tempo de atualização do relatório.

Comece pelo teste de rede, porque ele divide o problema em dois contextos.

Se __ptq.gif não aparece, o rastreamento não está disparando naquela página. Verifique nesta ordem: o snippet existe no código-fonte daquela URL específica e não só na home, o número no nome do arquivo .js é o Hub ID da sua conta, e o arquivo carrega com 200 ou 304 em vez de erro. Script ausente aponta para instalação ou cache; script com erro de carregamento aponta para Hub ID ou restrição de rede.

Se __ptq.gif aparece com 200 e o relatório está vazio, o dado está sendo enviado e o problema é de leitura. Confira o intervalo de datas, se o tráfego interno não está excluído das análises e se a URL testada pertence ao domínio filtrado no relatório.

Alguns cenários enganam times experientes:

• Código só em um template. A home tem o snippet, as páginas de curso não. O teste na home passa, o relatório fica quase vazio, e a conclusão errada é que o código não funciona.
• Portal antigo ainda no ar. Sites que trocaram de agência ou de conta ficam com o Hub ID anterior. O código funciona, só envia o dado para outro lugar.
• Bloqueador no navegador de quem testa. Extensões de privacidade barram a chamada. Testar em janela anônima elimina essa variável em dez segundos.
• Consentimento pendente. Com banner no modo opt-in, o rastreamento só dispara depois do aceite. Recarregar, aceitar e conferir de novo é parte do teste.
• Cache de CDN. A alteração foi publicada, mas a versão em cache segue servindo o HTML sem o snippet para boa parte dos visitantes.

Quando o dado passa a chegar, a etapa seguinte é interpretá-lo. Vale conhecer os recursos de análise de dados na HubSpot antes de concluir algo de um relatório com poucos dias de histórico, porque volume baixo em janela curta engana com facilidade.

O que o banner de consentimento muda no rastreamento e nos cookies?

O banner de consentimento da HubSpot opera tanto em páginas hospedadas na plataforma quanto em páginas externas que carregam o código de rastreamento. Cookies classificados como necessários são sempre implantados. Os demais dependem do tipo de banner escolhido, e essa escolha muda diretamente o que aparece nos relatórios de tráfego.

São três tipos de banner: notificação, que apenas informa; opt-in, que exige aceite antes de rastrear; e opt-out, que rastreia automaticamente com opção de recusa. Para consentimento inequívoco nos termos da LGPD, o tipo relevante é o opt-in.

E aí está a relação com o assunto deste artigo: no modo opt-in, o visitante que não clica em aceitar não gera page view rastreado.

Isso não é falha de instalação, é a privacidade funcionando como deveria, e explica por que o número da HubSpot pode ficar abaixo do que outras ferramentas de análise mostram. O relatório passa a medir visitas com consentimento, não visitas totais.

A HubSpot mantém na documentação a lista de cookies que implanta no navegador do visitante, com a função de cada um. É o insumo que a área jurídica pede para montar a política de cookies do site.

O tema se conecta com a discussão mais ampla de privacidade de dados dentro do CRM, que vai além do banner.

Uma nota de precisão: banner e registro de consentimento são meios de evidenciar consentimento livre, informado e inequívoco para uma finalidade determinada. Escolher o tipo de banner é decisão de conformidade, não de performance.

Perguntas frequentes sobre código de rastreamento HubSpot

Afinal, quando dar o código de rastreamento HubSpot por validado?

Quando você tiver evidência dos dois lados: o __ptq.gif com status 200 em pelo menos uma página de cada template do site e o page view correspondente aparecendo no relatório de tráfego. Um sem o outro não fecha o diagnóstico. O primeiro prova envio, o segundo indica recebimento e atribuição.

Antes de encerrar a tarefa, feche quatro pontos: o Hub ID confere, o snippet cobre todos os templates e não apenas a home, o cache foi limpo depois da publicação e o tipo de banner de consentimento está claro para quem vai ler os relatórios.

Vale enxergar essa etapa no lugar que ela ocupa: rastreamento é a primeira configuração que gera dado num projeto de implementação HubSpot , e é a que todas as análises posteriores herdam. A instalação malfeita aqui não aparece como erro, mas como número baixo, bem mais difícil de detectar.

Com o código validado, o passo seguinte é imediato: ver o dado chegando e aprender a ler o que ele mostra. É exatamente o que a configuração do HubSpot Analytics organiza, dos relatórios de origem de tráfego às métricas por página, para que o esforço de instalação se converta em decisão de marketing.