Referência da API de Eventos

A API de eventos do Hotjar permite que você envie eventos para o Hotjar usando JavaScript quando ações específicas ocorrem em seu site, salvando-os dentro do Hotjar como Eventos. Esses eventos podem ser usados para ajudar a filtrar os dados coletados de Recordings e mapas de calor, e para disparar a captura de sessão para iniciar ou aparecer widgets de feedback e pesquisas. 

• Visão geral
• A chamada da API de eventos
• Exemplos de chamadas da API de eventos
• Melhores práticas
• Testando Eventos

---

Visão geral

Os Eventos do Hotjar representam ações que um usuário realizou enquanto estava em seu site. Esses eventos são definidos e enviados ao Hotjar por meio do seu código do lado do cliente via API de Eventos do Hotjar. Esta API está disponível em todas as páginas que contêm o código de rastreamento do Hotjar.

Com JavaScript, você pode configurar seus próprios critérios para determinar que tipo de ação resulta em um evento sendo enviado ao Hotjar. O evento pode ser enviado assim que a página é carregada, quando um modal aparece, ou quando eles veem uma variação específica do conteúdo por meio de um teste A/B.

Por exemplo, pode ser útil rastrear usuários que adicionaram com sucesso um cartão de crédito durante um processo de checkout, adicionando um evento como, Adicionou Cartão de Crédito com sucesso. Você também pode se interessar em comparar sessões em que um cartão de crédito não foi adicionado com sucesso, adicionando um segundo evento, como Adição de Cartão de Crédito falhou. Ao passar eventos com base nas ações do usuário, você pode filtrar as Recordings pelos usuários que acionaram cada tipo de evento durante seu processo de checkout. Configurar esses eventos no código do seu site pode se parecer com isso:

fetch('/api/adicionar-cartao-de-credito', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
    hj('event', 'Adicionou Cartão de Crédito com sucesso')
    // lidar com a resposta do backend.
  }
)
.catch(error => {
  hj('event', 'Adição de Cartão de Crédito falhou')
})

*Consulte seus próprios desenvolvedores para determinar qual código será necessário para o seu site.

Como os critérios para enviar eventos são baseados no seu próprio código, o recurso é muito flexível, mas exigirá codificação personalizada do seu desenvolvedor web.

Voltar ao topo

A chamada da API de Eventos

Abaixo está o formato básico para uma chamada à API de Eventos:

hj('event', 'nome_da_acao');

• O primeiro parâmetro deve sempre conter o valor da string event.
• O segundo parâmetro é o nome personalizado atribuído ao seu evento. No exemplo acima, o nome do evento é nome_da_acao, mas isso pode ser qualquer coisa que você escolher. (Exemplo: 'abriu_modal', 'mostrou_variante_a', etc.)

Esteja ciente das limitações ao implementar eventos

• Nomeando seus Eventos.

  O nome do evento não deve exceder 250 caracteres e só pode conter um dos seguintes: caracteres alfanuméricos (a-z, A-Z, 0-9), espaços, sublinhados (_), traços (-), pontos (.), dois pontos (:) e barras (/).

• Há um limite de 10.000 eventos únicos por Site do Hotjar.

  Os Filtros do Hotjar só suportarão 10.000 eventos únicos por Site do Hotjar, com um número ilimitado de usuários associados a esses eventos. Se você exceder esse limite, apenas 10.000 dos eventos mais utilizados (ordenados de 0-9, a-Z) serão pesquisáveis na interface. Este é um total acumulado, então uma vez que o limite seja excedido, alguns eventos existentes podem se tornar não pesquisáveis no filtro. Se você exceder o limite, você pode excluir as gravações que contenham eventos que você não precisa mais. Cerca de 10 minutos após a exclusão, sua lista de filtros de eventos será atualizada.

• Apenas os primeiros 50 eventos únicos em uma única sessão serão pesquisáveis pelos filtros.
  Para otimizar o desempenho, o Hotjar avaliará apenas os primeiros 50 eventos únicos em uma sessão ao determinar se uma sessão corresponde aos critérios do filtro de Eventos. Isso significa que se uma sessão contém 51 eventos únicos, o último evento único que foi disparado durante a sessão não será detectado se você filtrar as gravações com base nesse evento. No entanto, todos os 51 eventos ainda serão visíveis na visualização de reprodução da gravação de cada sessão.

• Atualmente não é possível passar quaisquer propriedades de evento com o evento.

Voltar ao topo

Exemplos de Chamadas de API de Eventos

Abaixo estão alguns exemplos de casos práticos para eventos.

• Envie um evento para o Hotjar que você pode usar para disparar uma Pesquisa quando um usuário clica em um botão de Assinar.

  hj('event', 'inscrito_na_lista_de_emails');
  

• Envie um evento para o Hotjar relacionado a um erro específico, para que você possa filtrar suas gravações por usuários que encontraram um erro durante sua sessão.

  hj('event', 'erro_ocorrido');
  

• Envie um evento para o Hotjar para saber quando um usuário carrega uma variante específica de página durante um teste A/B.

  hj('event', 'variante_b_exibida');

Voltar ao topo

Melhores práticas

• Não envie Informações de Identificação Pessoal como um Evento.

  Informações de identificação pessoal (IIP) nunca devem ser usadas como eventos no Hotjar. Se você deseja conectar dados de sessão a usuários específicos, deve explorar o recurso de Atributos de Usuário em vez disso.

• Se você também estiver fazendo chamadas da API de Identificação, estas precisam ser executadas antes das chamadas da API de Eventos.

  Você pode querer combinar Eventos com segmentação baseada em Atributos de Usuário para disparar Surveys ou Feedback. Para configurar isso, a ordem de execução requer que a chamada da API de Identificação aconteça antes da chamada da API de Eventos, levando em consideração quaisquer chamadas assíncronas para outros serviços. Se a chamada da API de Eventos for executada antes que a chamada da API de Identificação tenha terminado a execução, o widget de Survey ou Feedback não será exibido.

• Eventos não podem ser usados para coletar endereços de e-mail ou IP, ou números com 9 ou mais dígitos.

  Como atualmente não há como usar nossa Ferramenta de Consulta de Usuário com eventos, eles não podem ser usados para coletar e-mails, endereços IP ou números com 9 ou mais dígitos para evitar que números de cartão de crédito sejam enviados ao Hotjar. Essa decisão foi baseada no Regulamento Geral de Proteção de Dados (GDPR). Se você deseja coletar endereços de e-mail com o consentimento do seu usuário e de acordo com o GDPR, você pode fazer isso com Atributos de Usuário.

• O Código de Rastreamento do Hotjar precisa ser carregado antes de enviar quaisquer Eventos.

  O objeto hj() não pode ser acessado até que o Código de Rastreamento do Hotjar tenha sido executado na página. Se o script que chama a API de Eventos for adicionado antes do seu Código de Rastreamento do Hotjar, ocorrerá um erro e o evento não será reconhecido. Se, por algum motivo, a API de Eventos estiver sendo acessada antes que o Código de Rastreamento do Hotjar tenha sido executado, então você pode adicionar a seguinte linha de código antes que o código da API de Eventos seja chamado:

  window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments);};

• Para sites de e-commerce, evite enviar informações específicas do produto.

  Isto inclui informações como códigos SKU. Geralmente, URLs são mais úteis e são capturadas por padrão.

• Tenha cuidado ao enviar valores de objetos como camadas de dados do GTM.

  Estes frequentemente contêm mais dados do que você espera.

• Ao evitar passar qualquer coisa como datas ou timestamps.
• Ao evitar passar qualquer coisa de URLs como códigos de referência.
• Ao evitar passar logs de erros detalhados.

Voltar ao topo

Testando Eventos

Seguir os passos abaixo permitirá que você confirme se suas chamadas da API de Eventos são recebidas com sucesso pelo Hotjar. Se você não está familiarizado com o console do seu navegador ou ferramentas de desenvolvedor, considere envolver um membro da equipe que tenha mais conhecimento dessas ferramentas ou um desenvolvedor web para ajudá-lo.

Ative os logs de depuração do Hotjar no console do seu navegador.

Abra a página onde você deseja testar o Evento e adicione o parâmetro ?hjDebug=1 ao final da URL. Aqui estão alguns exemplos de como isso pode parecer:

https://www.example.com/?hjDebug=1
OU
https://www.example.com/?utm_1234&hjDebug=1

Abra o console do seu navegador.

Se você não está familiarizado com as ferramentas de desenvolvedor do seu navegador, ou com o console, confira este guia para aprender como abrir o console do seu navegador.

Dispare o evento manualmente.

Para disparar o evento manualmente, adicione o código da API de Eventos no console do seu navegador e pressione Enter ou Return no seu teclado. Se o evento for disparado com sucesso, você verá um log de confirmação semelhante a este:

Também recomendamos que você siga os passos que seu usuário seguiria, para disparar o evento automaticamente. Se o evento for disparado automaticamente, então você saberá que seu código foi implementado com sucesso.

Se o mesmo evento for detectado ao ser disparado manualmente, mas não automaticamente ao testar a jornada do usuário, então você pode precisar revisar seu código e os critérios que determinam quando a chamada da API de Eventos é enviada.

Voltar ao topo