Gravação sem evento é palheiro sem ímã. Veja como usar a Events API e a Identify API do Hotjar, os limites que quebram implementações e como levar os dados para fora da ferramenta.
Índice do artigo
- Eventos x atributos: qual usar?
- Events API: a sintaxe e os limites
- Enviando eventos do Hotjar pelo GTM
- Identify API: atributos de usuário
- User ID: a regra que evita dor de cabeça
- Privacidade: o que nunca enviar
- Levando dados para fora: webhooks, Zapier e API
- Os erros que mais aparecem
- Perguntas frequentes sobre eventos no Hotjar
O Hotjar coleta milhares de gravações por mês. Sem eventos, encontrar a sessão da pessoa que tentou pagar com Pix e falhou é caçar agulha no palheiro. Com eventos e atributos, é um filtro.
Eventos x atributos: qual usar?
São duas APIs com funções diferentes. Eventos servem para reagir a uma ação ou mudança (um modal aberto, um erro exibido, a variante vista num teste A/B) quando você não precisa guardar aquilo associado ao usuário. Atributos descrevem quem é o usuário: plano, total gasto, data da primeira compra.
A frase que resume: evento é o que aconteceu na sessão; atributo é o que se sabe sobre a pessoa.
Events API: a sintaxe e os limites
A chamada tem dois parâmetros: a string event e o nome que você escolher.
hj('event', 'checkout_erro_pagamento');
Com eventos você filtra gravações e mapas de calor, dispara o início da captura de sessão ou faz uma pesquisa aparecer. Isso é o que torna o evento valioso para CRO: gravar só as sessões que chegaram ao checkout, ou abrir uma pesquisa de saída só para quem viu erro de frete.
Os limites: nomes de evento com até 250 caracteres, apenas letras, números, underscore, hífen, espaço, ponto, dois-pontos, barra vertical e barra; e até 10.000 eventos únicos por site.
Esse limite de 10 mil parece alto até alguém colocar o ID do pedido no nome do evento. Nome de evento é categoria, nunca valor dinâmico.
Enviando eventos do Hotjar pelo GTM
No Google Tag Manager, use uma tag de HTML personalizado com o acionador da ação que você quer medir. O detalhe que resolve boa parte dos “o evento não chega”: a linha que cria a fila do hj precisa estar dentro das mesmas tags script do evento, logo acima da chamada.
<script>
window.hj = window.hj || function(){(hj.q = hj.q || []).push(arguments);};
hj('event', 'lead_formulario_enviado');
</script>
Sem as tags script, o GTM injeta o código como HTML comum e ele pode aparecer como texto na página.
Boa prática: o acionador vem de um evento da camada de dados, e o nome do evento no Hotjar é o mesmo do GA4.
Identify API: atributos de usuário
A Identify API envia dados sobre os usuários, salvos como User Attributes, usados para filtrar gravações, segmentar pesquisas e fazer consulta e exclusão de dados por User ID.
hj('identify', userId, {
total_gasto: 500,
primeira_compra: '2026-06-20T00:00:00Z',
plano: 'premium'
});
O segundo parâmetro é o ID do usuário na sua base, ou null quando ele não é conhecido. Limites: até 100 atributos por site, nomes com no máximo 50 caracteres, valores do tipo número, texto de até 200 caracteres, data ISO-8601 ou booleano.
Dois cuidados. Primeiro, chame o identify a cada carregamento de página, após cada mudança de URL em single-page apps e sempre que um valor mudar. Segundo, se você combina eventos e atributos para exibir pesquisas, o identify precisa executar antes do evento; se o gatilho vier primeiro, a pesquisa não aparece.
A Identify API está disponível nos planos Business e Scale. Confira o plano antes de prometer segmentação ao time.
User ID: a regra que evita dor de cabeça
O User ID deve ser único, não conter dado pessoal e nunca mudar; se mudar, o Hotjar trata como outra pessoa. Por isso, e-mail como ID é má ideia: e-mails mudam. Use a chave primária do seu banco.
O ganho de fazer certo: quando o usuário é identificado, o Hotjar conecta ao User ID as sessões anteriores feitas no mesmo dispositivo antes do login. Você passa a ver a jornada do anônimo ao cliente.
Privacidade: o que nunca enviar
- Dado pessoal nunca vai em nome de evento.
- E-mail só no atributo reservado email; outros atributos de texto com e-mail são rejeitados.
- Com usuário não identificado (ID null), nenhum atributo pode conter dado pessoal: o Hotjar não consegue localizar nem excluir essa informação sem apagar o site inteiro.
A Identify API vem desativada por padrão, e ativá-la exige aceitar o acordo de processamento de dados do Hotjar. Envolva o jurídico antes de ligar.
Como testar: ative o debug mode do Hotjar no navegador e confira os atributos ativos em Settings > User Attributes.
Levando dados para fora: webhooks, Zapier e API
Pesquisa respondida que ninguém lê não vira melhoria. Respostas de pesquisa podem ser encaminhadas para Slack, Microsoft Teams, URLs de webhook, a API de respostas e vários e-mails, além de fluxos no Zapier. A integração nativa com Slack só publica em canais públicos; para privados, use o Zapier, que exige plano Business ou Scale.
Para automação mais pesada, há a API REST: exportação de respostas de pesquisa e automação de consulta e exclusão de usuários, com OAuth por client credentials, respostas em JSON, paginação por cursor e limite de 3.000 requisições por minuto, nos planos Scale. Para projetos com npm, há o SDK @hotjar/browser.
Os erros que mais aparecem
- ID de pedido, e-mail ou valor dinâmico no nome do evento.
- Tag de HTML personalizado no GTM sem a linha de fila do hj.
- Identify chamado só no login, e nunca de novo em SPA.
- Evento disparando antes do identify, e a pesquisa segmentada não aparece.
- E-mail usado como User ID.
Perguntas frequentes sobre eventos no Hotjar
O que é a Events API do Hotjar?
É a chamada JavaScript hj(‘event’, ‘nome’) que registra uma ação do usuário para filtrar gravações e mapas de calor, iniciar captura de sessão e disparar pesquisas.
Como enviar eventos para o Hotjar pelo Google Tag Manager?
Crie uma tag de HTML personalizado com a linha de fila do hj seguida da chamada do evento, dentro das mesmas tags script, e associe ao acionador da ação.
Qual a diferença entre evento e user attribute no Hotjar?
O evento registra o que aconteceu na sessão; o atributo descreve o usuário e fica associado ao ID dele.
Quantos eventos o Hotjar aceita?
Até 10.000 eventos únicos por site, com nomes de até 250 caracteres.
Posso enviar e-mail para o Hotjar?
Só no atributo reservado email da Identify API, com usuário identificado e respeitando a base legal definida pelo jurídico.
O Hotjar tem webhook?
Sim, para respostas de pesquisa, além de integrações com Slack, Teams, Zapier e a API de respostas.