Referência da API de Identificação

A API de identificação do Hotjar permite que você envie dados sobre seus usuários para o Hotjar usando Javascript, salvando-os como Atributos de usuário. Esses Atributos de usuário podem ser usados pelo Hotjar para habilitar filtragem avançada e segmentação, proporcionando insights de qualidade mais rapidamente do que antes. Você pode enviar até 100 atributos de usuário em qualquer site, com qualquer número de usuários associados a esses atributos.

Os Atributos de usuário podem ser usados para filtrar Recordings e segmentar Surveys e widgets de Feedback, além de realizar consultas e solicitações de exclusão de usuário por ID de usuário.

Siga os links abaixo para saber mais sobre Atributos de usuário:

• Visão geral
• Manuseio de IDs de usuário
• Realizando chamadas para Identificar
• Valores de Atributos de usuário
• Manuseio de endereços de e-mail
• Exemplos de envio de Atributos de usuário para o Hotjar
• Usando a API de Identificação de forma legalmente compatível
• Desabilitando Atributos de usuário
• Excluindo Atributos de usuário
• Melhores práticas
• Perguntas frequentes

---

Visão geral

html

Os Atributos de Usuário são valores de dados sobre os usuários do seu site enviados para o Hotjar a partir do seu código do lado do cliente por meio da API de Identificação do Hotjar. Esta API está disponível em todas as páginas que contêm o código de rastreamento do Hotjar.

Esses dados são enviados para o Hotjar em pares de chave-valor como uma chamada AJAX assíncrona para os servidores do Hotjar. Esses valores são associados a um ID de Usuário, um valor unicamente identificável enviado para o Hotjar no seu código a partir de um valor de ID de usuário do seu banco de dados de usuários. Isso permite que o Hotjar associe os dados coletados sobre eles com o mesmo ID de usuário que você usa no seu próprio banco de dados, bem como consulte as informações do usuário mantidas no Hotjar sobre esse usuário.

Há 4 fases no processo de envio de Atributos de Usuário para o Hotjar e de usá-los com o Hotjar.

1. Obtenha os dados do seu site.
2. Passe os dados para o Hotjar por meio da API de Identificação.
3. O Hotjar armazena os dados sobre cada usuário como Atributos de Usuário associados ao seu user_id.
4. Agora você pode usar as ferramentas do Hotjar para segmentar e filtrar por Atributos de Usuário.

Voltar ao topo

Fazendo chamadas para Identificar

Antes de começar a fazer chamadas para Identificar, os Atributos de Usuário devem estar habilitados nas configurações do seu Hotjar para cada site que você deseja usar Atributos de Usuário.

Habilitando e desabilitando Atributos de Usuário

A capacidade de acessar a API de Identificação e os Atributos de Usuário serão habilitados por padrão se esse recurso estiver incluído no seu plano do Hotjar. No entanto, se os Atributos de Usuário foram desabilitados no passado, talvez você precise reabilitá-los para uso.

Na sua página de Atributos de Usuário (Configurações > Atributos de Usuário), encontre o Site ao qual deseja adicionar Atributos de Usuário usando o menu suspenso de seleção. Você verá algo assim mostrando o status da implementação dos seus Atributos de Usuário:

Você também pode desabilitar Atributos de Usuário nesta página. Depois de selecionar um Site com Atributos de Usuário habilitados, clique em Desabilitar Atributos de Usuário. Após fazer isso, novas chamadas para a API serão bloqueadas. O botão "Desabilitar Atributos de Usuário" só aparecerá depois que os dados de atributos de usuário forem recebidos pelo Hotjar, mas não antes.

Quaisquer relatórios que dependem de Atributos de Usuário para fins de segmentação serão desabilitados, e você não poderá reabilitá-los a menos que altere suas opções de segmentação ou reabilite os Atributos de Usuário.

Se você deseja impedir que Atributos de Usuário sejam enviados no futuro, você deve remover o código da API de Identificação do seu site. Uma vez que o código é excluído do seu site, os Atributos de Usuário coletados anteriormente ainda existirão, mas não serão mais atualizados ou adicionados a novos usuários do seu site.

A chamada da API

Aqui está o formato de uma chamada para a API de Identificação:

hj('identify', userId, { 
    user_attribute: value
});

• O primeiro parâmetro deve sempre conter o valor da string "identify".
• O segundo deve ser uma string contendo o ID do usuário para um usuário em seu site, do seu próprio banco de dados de usuários, ou nulo se não for conhecido.
• O terceiro é uma série de pares chave-valor dentro de um objeto. A chave fornece o nome do Atributo do Usuário, e o valor define tanto o tipo de Atributo do Usuário quanto seu valor para esse usuário.

Os valores passados para essa chamada devem vir do código do seu próprio site. Esses valores podem ser obtidos diretamente de seus servidores ou gerados do lado do cliente.

Uma vez enviados para o Hotjar, esses atributos e os valores para cada usuário são armazenados nos servidores do Hotjar. Cada vez que uma chamada para Identificar é feita, os valores armazenados nos servidores do Hotjar serão substituídos pelos valores mais recentes para esses atributos.

Você pode consultar todos os atributos enviados para o Hotjar na página de Configurações de Atributos do Usuário. Você pode usar o recurso de Consulta de Usuário para inspecionar quais valores foram passados para um usuário específico em seu site.

Desde que um usuário seja identificado durante sua sessão, o Hotjar é capaz de associar IDs de Usuário e Atributos do Usuário a uma Gravação de sessão, e oferecer segmentação de widget de feedback detalhada, permitindo que você colete feedback direcionado de usuários específicos usando Feedback e Surveys. Por exemplo: "Quero que esta Pesquisa seja direcionada apenas para clientes pagantes que fizeram uma compra há mais de 10 dias".

Voltar ao topo

Manuseio de IDs de Usuário

O segundo argumento passado para o Hotjar através da chamada da API de Identificação deve ser um ID de usuário exclusivamente identificável do banco de dados do seu próprio site. Os Atributos do Usuário estão associados a este ID de Usuário.

O ID de Usuário deve ser único por usuário, mas não deve conter informações pessoais. Também deve ser um valor que nunca muda para este usuário. Uma vez que você definiu um ID de Usuário no Hotjar, ele não pode ser alterado. Se for alterado, o Hotjar considerará isso como um usuário totalmente novo.

Se um ID de Usuário for conhecido, o ID do Hotjar do usuário será associado ao seu ID de Usuário. Um ID do Hotjar é um ID de usuário exclusivo gerado aleatoriamente, criado no nível do Site do Hotjar. Se um usuário não tiver um ID de Usuário quando visitar um site inicialmente, então o ID do Hotjar será associado ao seu ID de Usuário assim que a chamada para a API de Identificação com um ID de Usuário for feita.

É útil trabalhar isso com um exemplo.

Vamos dizer que tivemos uma usuária, Rachel. Ela visita o site 3 vezes em 2 dispositivos diferentes.

html

• Sessão A - Rachel visita radbooks.com em seu tablet.
  • Ela ainda não é uma usuária do site e recebe um ID do Hotjar de 123
• Sessão B - Rachel então visita o site em seu celular.
  • Ela ainda não é uma usuária e recebe um ID do Hotjar de 456
• Sessão C - Rachel retorna ao site pelo celular.
  • O Hotjar a reconhece com o ID do Hotjar de 456.
  • Ela então registra uma conta.
  • Sua chamada para Identificar atribui a ela um ID de Usuário de ABC, usando o mesmo ID de Usuário que você tem para ela em seu banco de dados.

Como a associamos a um ID de Usuário em seu site, conectamos todos os dados associados ao ID do Hotjar 456 com seu ID de Usuário ABC, mesmo que ela não estivesse logada durante a Sessão B.

Se Rachel então continuar a visitar o site em seu tablet em uma 4ª sessão, e desta vez fizer login, o Hotjar irá juntar os dados das Sessões A, B e C, fornecendo a você uma visão completa de suas interações com seu site.

E se você não tiver um ID de Usuário?

Se o ID de Usuário não for conhecido, então você deve passar um valor nulo para o segundo parâmetro. Quando você faz isso, quaisquer Atributos de Usuário passados para a API de Identificação serão associados ao ID do Hotjar do usuário. 

Valores de Atributos de Usuário

Você pode passar os seguintes valores para uma chave de Atributo de Usuário usando a API de Identificação. Caracteres especiais não podem ser usados neste momento.

Tipo	Valores	Limitações/Notas
Número	Inteiros ou decimais	Mínimo: -9007199254740991 Máximo: 9007199254740991
Strings	Texto	Máximo de 200 caracteres Sensível a maiúsculas e minúsculas Suportado UTF-8 Não envie endereços de e-mail
Data	Strings de data ISO-8601	Do JavaScript, use a função toISOString() em um objeto de data.
Booleano	Valores true ou false

Manuseio de endereços de e-mail

No momento, há uma chave de Atributo de Usuário para endereços de e-mail: email. Os endereços de e-mail devem ser passados como strings para o email. Por exemplo:

hj('identify', userId, {
	email: 'test@test.com' 
});

Se quaisquer outros Atributos de Usuário de tipo string contiverem um endereço de e-mail, estes serão rejeitados, significando que você deve usar apenas `email` para passar endereços de e-mail.

Exemplos de passagem de Atributos de Usuário para o Hotjar

Identificando clientes pagantes

Aqui está um exemplo, onde queremos informar ao Hotjar quanto dinheiro alguém gastou em seu site.

hj('identify', userId, {
	total_spend: 500
});

Múltiplos atributos podem ser passados adicionando mais pares chave-valor no objeto. Talvez você queira que o Hotjar saiba quando eles se tornaram clientes pela primeira vez?

hj('identify', userId, {      
	total_spend: 500,
	first_purchase: '2019-06-20Z'
});

Aqui estamos informando ao Hotjar que seu usuário se tornou um cliente do seu serviço usando uma string de data ISO8601.

Identificando Atributos para Usuários Desidentificados

Às vezes é útil rastrear informações sobre usuários em seu site, mesmo que eles ainda não sejam usuários ou clientes pagantes. Digamos que você queira rastrear a fonte de referência e a variante do teste A-B da página de destino que um lead em potencial acessou:

hj('identify', null, {
    ab_test: 'variante-A',
    referrer: 'facebook_pago'
});

Isso seria útil se você quisesse direcionar uma Pesquisa para usuários na variante-A, ou apenas para aqueles que chegaram até você a partir de anúncios pagos do Facebook, por exemplo.

Usando a API de Identificação de forma Legalmente Conforme

A API de Identificação é desativada por padrão, tornando fácil evitar capturar acidentalmente informações pessoais até que você tenha lidado adequadamente com as preocupações de privacidade. Ao ativar os Atributos de Usuário, você pode estar passando os dados pessoais de seus usuários finais para o Hotjar. Exigimos que você reconheça suas obrigações legais ao fazer isso e aceite o Acordo de Processamento de Dados do Hotjar.

É sua responsabilidade usar esse recurso de maneira legalmente conforme, consistente com as leis do seu país e dos países visitados por seus usuários. Visite nossa página de privacidade para saber mais sobre a abordagem do Hotjar à privacidade do usuário. Ao usar os Atributos de Usuário, você deve estar ciente e conformar-se com os Termos de Serviço e a Política de Uso Aceitável do Hotjar.

Voltar ao topo

Manuseio de Consultas e Solicitações de Exclusão de Usuários

É possível consultar e excluir os dados de um usuário usando seu ID de usuário. Saiba mais sobre isso em nosso artigo "Como Usar a Consulta de Usuário". É importante observar que se você conhece o ID de usuário de um usuário e o endereço de e-mail, você deve procurar suas informações com ambos. Esta é a única maneira de garantir que todas as informações pessoais que o Hotjar possui sobre esse usuário tenham sido consultadas e excluídas.

Voltar ao topo

Desativando Atributos de Usuário

Para evitar que mais Atributos de Usuário sejam enviados para o Hotjar, você deve desativar os Atributos de Usuário.

Enquanto os Atributos de Usuário estiverem ativados em seu site, se você deseja impedi-los de serem enviados no futuro, você deve remover o código em seu site que os envia para o Hotjar. Uma vez que o código é excluído do seu site, os Atributos de Usuário coletados anteriormente ainda existirão, mas não serão mais atualizados ou adicionados a novos usuários do seu site.

Voltar ao topo

Excluindo Atributos de Usuário

Os Atributos de Usuário podem ser excluídos na página de gerenciamento de Atributos de Usuário clicando no ícone de lixeira à direita do atributo. Apenas membros da equipe com permissões de 'Leitura e gravação' ou superiores podem excluir Atributos de Usuário.

Quando um atributo é excluído, ele desaparecerá imediatamente da aplicação Hotjar. No entanto, o atributo ainda é armazenado no backend por 7 dias antes de ser excluído permanentemente. Os dados associados ao atributo são ignorados durante o período de 7 dias. Isso é para evitar que os dados sejam enviados devido a problemas de cache.

Se você deseja recriar um atributo que foi excluído, você precisará esperar 7 dias antes que o atributo possa ser recriado com sucesso.

Voltar ao topo

Melhores Práticas

Quando fazer chamadas de API para Identificação

Você deve fazer chamadas para Identificação sempre que:

• Uma página é carregada com os valores mais recentes (mesmo que não tenham mudado).
• Após uma alteração de URL em aplicativos de página única.
• Toda vez que uma alteração é feita. Por exemplo, se você deseja rastrear a última compra em uma loja, você gostaria de atualizar esse atributo de usuário assim que uma compra for feita.

Cada chamada atualizará os Atributos de Usuário no Hotjar com os valores mais recentes. Quando uma gravação de sessão termina, a gravação salva os valores mais recentes no momento em que a sessão termina. Quando uma chamada é feita, mas os valores não foram atualizados, a solicitação de rede não será enviada para evitar solicitações AJAX desnecessárias.

Combinando chamadas de API de Identificação com gatilhos para segmentação de Surveys/Widgets de Feedback

Se você planeja combinar Eventos com segmentação de Atributos de Usuário para Surveys ou Widgets de Feedback, você deve garantir que a chamada de Identificação tenha ocorrido antes do gatilho em sua ordem de execução, levando em consideração quaisquer chamadas assíncronas a outros serviços. Se o gatilho for executado antes que a chamada da API de Identificação tenha terminado, o widget de Survey/Feedback não será exibido.

Enfileirando chamadas para a API antes que o Hotjar seja carregado

Se este script for adicionado antes do seu código de rastreamento do Hotjar, ocorrerá um erro.

O objeto hj() não pode ser acessado até que a tag de código de rastreamento do Hotjar tenha sido executada. Se, por algum motivo, você acessar a API de identificação antes que o código de rastreamento tenha sido executado, você pode adicionar a seguinte linha de código antes de chamar a API:

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

Testando Atributos do Usuário

Há algumas maneiras de testar se os Atributos do Usuário estão sendo enviados corretamente através da API de identificação.

• Assim que o código estiver ativo em sua página e tiver sido disparado pelo menos uma vez, você pode visitar a página de configurações de Atributos do Usuário para ver se o Atributo do Usuário capturado pelo Hotjar está ativo em sua página.
• Você pode ativar o modo de depuração do Hotjar em seu navegador para ver se as chamadas da API de identificação estão sendo enviadas com sucesso para o Hotjar durante sua sessão.
• Para usuários com valor nulo, você pode usar qualquer endereço de e-mail que possua para consentir em conectar respostas de Feedback através de uma Pesquisa ou Feedback. Isso permitirá que você veja quais Atributos do Usuário estão sendo enviados para usuários não identificados, o que é especialmente útil para verificar se você não está enviando acidentalmente informações de identificação pessoal para o Hotjar. É importante observar que usuários que não consentiram em conectar o Feedback não podem ser pesquisados dessa maneira, portanto, para fins de teste, você deve configurar um widget de feedback para conceder consentimento com seu próprio endereço de e-mail.

Voltar ao topo