Disponibilidade do plano
Os clientes do plano podem acessar os recursos de Exportação de respostas de pesquisa, Consulta de usuário e solicitação de exclusão.
Os clientes do plano podem acessar os recursos de Consulta de usuário e solicitação de exclusão.
Agende uma ligação com nossa equipe de vendas para saber mais sobre os recursos do plano de escala. Os clientes do plano podem acessar os recursos de Exportação de respostas de pesquisa, Consulta de usuário e solicitação de exclusão. Agende uma ligação com nossa equipe de vendas para saber mais sobre os recursos do plano de escala.
Os clientes do plano podem acessar os recursos de Consulta de usuário e solicitação de exclusão.
Referência da API
Visão geral
A API do Hotjar é uma API HTTP baseada em JSON:
- É orientada a recursos (como REST)
- Aceita corpos de solicitação em JSON
- Retorna respostas em JSON
- Usa verbos (métodos) HTTP padrão
- Usa códigos de status HTTP para comunicar o status
- Usa o fluxo de credenciais do cliente OAuth para autenticação
Todas as chamadas de API são feitas para o mesmo domínio base: https://api.hotjar.io
Autenticação
A API do Hotjar usa uma combinação de chaves de API e o fluxo de credenciais do cliente OAuth para autenticação. Você pode gerar uma chave de API de dentro do aplicativo Hotjar. As chaves de API são compostas por um par de itens: o ID do cliente e o segredo do cliente. Quando você deseja usar a API, você deve:
- Enviar uma solicitação para o endpoint do token com o ID do cliente e o segredo do cliente
- Receber em resposta um token de portador temporário
- Enviar o token de portador com todas as outras chamadas de API via o Cabeçalho HTTP de Autorização
As chaves de API concedem acesso a muitos privilégios, portanto, você deve mantê-las em segredo. Não as compartilhe em áreas de acesso público, como Gitlab ou incorporadas em um aplicativo. As chaves de API são destinadas à comunicação máquina a máquina, onde a chave de API é mantida em segredo.
Obtendo o token de portador
Para obter um token de acesso, você deve enviar uma solicitação HTTP POST para /v1/oauth/token. A solicitação deve ser codificada como application/x-www-form-urlencoded (isso é um requisito do OAuth) e deve incluir três parâmetros:
- grant_type deve ser definido como client_credentials
- client_id deve ser definido como o ID de cliente da sua chave de API
- client_secret deve ser definido como o segredo do cliente da sua chave de API
Aqui está um exemplo simplificado:
POST /v1/oauth/token HTTP/1.1
Host: api.hotjar.io
grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx
A resposta, se bem-sucedida, é um objeto JSON de resposta contendo três chaves:
- token_type que será definido como Bearer
- expires_in que especifica o número de segundos até que o token de portador expire
- access_token que é o próprio token de portador
Aqui está um exemplo de resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"<token>",
"token_type":"Bearer",
"expires_in":3600,
}
Usando o token de portador
Você deve enviar o token de portador, obtido pelo método acima, via o cabeçalho HTTP Authorization ao fazer chamadas de API. O valor do cabeçalho deve ser Bearer <token aqui>. Aqui está um exemplo simplificado:
GET /v1/sites/1/surveys HTTP/1.1
Host: api.hotjar.io
Authorization: Bearer token_goes_here
No caso de suas solicitações não incluírem o cabeçalho, ela responderá com um código de status HTTP 401. Se o token for inválido, ou sua chave de API não tiver permissão para realizar a ação solicitada, ela responderá com um código de status HTTP 403.
Limitação de taxa
Atualmente, a API do Hotjar é limitada por endereço de origem e está limitada a 3000 solicitações por minuto (50 por segundo). Pretendemos avaliar mais restrições de limitação de taxa no futuro. Se você fizer muitas solicitações, a API responderá com um código de status HTTP 429.
Respostas e Erros
O código de status HTTP é autoritário; se o código de status estiver na faixa 2XX, a chamada de API foi um sucesso, se o código de status estiver na faixa 4XX, houve um erro do cliente, e se o código de status estiver na faixa 5XX, houve um erro do servidor.
Se o endpoint da API retornar dados, eles serão retornados como JSON. Nestes casos, a resposta de nível superior será um objeto JSON (em vez de uma matriz). Se o endpoint retornar vários objetos (linhas), eles serão enviados como uma matriz sob a chave results. Uma chave de next_cursor de nível superior será incluída na resposta para endpoints com paginação (veja abaixo).
Em alguns casos, quando um erro é retornado, informações adicionais sobre o erro serão incluídas. Nestes casos, a resposta será codificada em JSON e incluirá os seguintes campos:
- code - uma string destinada a ser legível por máquina, contendo o código de erro
- msg - uma string, legível por humanos, explicando a causa do erro.
Paginação
A API do Hotjar utiliza paginação baseada em cursor. Quando um endpoint suporta paginação, você pode enviar um parâmetro limit para especificar quantos itens deseja receber. Quando você faz a primeira solicitação, receberá na resposta um campo next_cursor. Para obter a próxima página de itens quando fizer a próxima solicitação, passe o valor de next_cursor como um parâmetro chamado cursor. A API então usa esse valor para retornar a próxima página de itens. Quando não houver resultados adicionais, next_cursor é null.
Versionamento
A API do Hotjar utiliza um número de versão "global" em vez de cada endpoint individual ser versionado. Não introduziremos alterações incompatíveis com versões anteriores dentro de uma versão. Atualmente, temos apenas uma versão da API (v1) e podemos introduzir outras versões no futuro. Garantiremos que, se no futuro decidirmos parar de oferecer suporte a uma versão da API, daremos pelo menos seis meses de aviso antes de remover o suporte.
Referência da API
Respostas de Pesquisas
Listar Pesquisas
As respostas são classificadas automaticamente e não podem ser filtradas via API
Ao listar as respostas da pesquisa, as respostas são classificadas por data de criação em ordem decrescente. Isso significa que as respostas mais recentes são mostradas primeiro. Neste momento, não é possível filtrar respostas, por exemplo, filtrar respostas de uma data específica.
GET /v1/sites/:site_id/surveys
- site_id: O identificador único do site. Este ID pode ser encontrado na página Sites e Organizações sob a respectiva organização.
Parâmetros de URL (opcionais):
- limit: O número de pesquisas a serem retornadas na resposta. Máximo de 100.
- cursor: O cursor a ser usado para buscar uma página específica.
- with_questions: Sinalizador (true/false) indicando se as informações da pergunta devem ser incluídas na resposta. Por padrão, não são incluídas.
Campos de resposta:
- resultados: Uma lista de itens de pesquisa. Cada pesquisa contém os seguintes campos:
- id (string): O identificador único da pesquisa.
- url (string): O URL da pesquisa para a API do Hotjar.
- created_time (datetime): O horário de criação da pesquisa no formato rfc3339.
- updated_time (datetime): O horário de atualização da pesquisa no formato rfc3339.
- is_enabled (boolean): Sinal indicando se a pesquisa está habilitada ou não.
- nome (string): O nome da pesquisa.
- responses_url (string): O URL da API do Hotjar para as respostas desta pesquisa.
- tipo (string): O tipo de pesquisa. Pode ser um dos seguintes: link, full_screen ou popover.
- perguntas: Uma lista de itens de pergunta. Incluído opcionalmente se a flag estiver definida como true nos parâmetros da solicitação.
- id (string): O identificador único da pergunta.
- is_required (boolean): Sinal indicando se a pergunta é obrigatória.
- texto (string): O texto da pergunta.
- tipo (string): O tipo da pergunta. Os valores possíveis são reaction, long-text, short-text, single-option, multiple-option, email, rating-1-5, rating-1-7, nps, statement e thank-you.
- image_url (url opcional): O URL da imagem associada à pergunta, se houver uma.
- escolhas (lista opcional de objetos de escolha): As escolhas possíveis que os usuários podem selecionar. Este campo será usado apenas para os tipos de pergunta single-option ou multiple-option.
- texto (string): O texto da escolha
- allow_comment (boolean): Sinal indicando se os usuários podem comentar se selecionarem esta escolha.
- etiquetas (Objeto de etiqueta opcional): Informações sobre a nomenclatura da etiqueta baixa e da etiqueta alta. Este campo será usado apenas para os tipos de pergunta rating-1-5, rating-1-7, nps e reaction.
- low_label (string): A nomenclatura para a opção de pontuação mais baixa da pergunta.
- high_label (string): A nomenclatura para a opção de pontuação mais alta da pergunta.
- sentiment_analysis_enabled (boolean): Indica se as respostas passam pela análise de sentimento ou não.
- next_cursor (string): O cursor para a próxima página.
Resposta de exemplo:
{
"next_cursor": "gAAAAABj90lFO37F7V3M0GLNa-cp0QIqq91P3faMKqptoVZpRGn8LH9lufXhTX2MOtv566sVsbVz_YGS9FYp_N19DNK8brCAhEbIFKcgYUjh6vX2FjRgtoELfj9E3_kggNZ5DF8Ul3oE",
"results": [
{
"created_time": "2023-02-23T11:08:53.287Z",
"id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
"is_enabled": false,
"name": "Nome da minha pesquisa",
"responses_url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
"type": "Popover",
"url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
"questions": [
{
"choices": null,
"id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
"image_url": null,
"is_required": true,
"labels": null,
"text": "O que você acha da nossa API?",
"type": "long-text"
}
],
"sentiment_analysis_enabled": false
}
]
}
Buscar Pesquisa
GET /v1/sites/:site_id/surveys/:survey_id
- site_id: O identificador único do site. Este ID pode ser encontrado na página Sites e Organizações sob a respectiva organização.
- survey_id: O identificador único da pesquisa.
Campos de resposta:
Os campos de resposta são os mesmos do item de Pesquisa descrito no endpoint Listar Pesquisas acima. As perguntas estão sempre incluídas neste endpoint.
Resposta de exemplo:
{
"created_time": "2023-02-23T11:08:53.287Z",
"id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
"is_enabled": false,
"name": "Nome da minha pesquisa",
"responses_url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
"type": "Popover",
"url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
"questions": [
{
"choices": null,
"id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
"image_url": null,
"is_required": true,
"labels": null,
"text": "O que você acha da nossa API?",
"type": "long-text"
}
],
"sentiment_analysis_enabled": true
}
Listar Respostas da Pesquisa
GET /v1/sites/:site_id/surveys/:survey_id/responses
- site_id: O identificador único do site. Este ID pode ser encontrado na página Sites e Organizações sob a respectiva organização.
- survey_id: O identificador único da pesquisa.
Parâmetros de URL (opcionais):
- limite: O número de respostas da pesquisa a serem retornadas na resposta. Máximo de 100.
- cursor: O cursor a ser usado para buscar uma página específica.
Campos de resposta:
- resultados: Uma lista de itens de Resposta de Pesquisa. Cada Resposta de Pesquisa contém os seguintes campos:
- id (string): O identificador único da resposta.
- respostas (lista de objetos Resposta de Pesquisa). Cada Resposta de Pesquisa contém os seguintes campos:
- question_id (string): O identificador da pergunta.
- resposta (string): A resposta.
- comentário (string): Comentário opcional fornecido pelo usuário.
- tags (lista de objetos Tag de Resposta de Pesquisa). Cada Tag de Resposta de Pesquisa contém os seguintes campos:
- nome (string): O nome da tag.
-
sentimento (string): O sentimento do texto da resposta. Pode ser um dos valores "positivo", "negativo", "neutro" ou `null`. O valor null é definido para respostas não textuais ou quando nenhum sentimento foi atribuído. A chave de sentimento só estará presente quando fizer parte do seu plano de produto Ask.
- navegador (string): O navegador no qual a resposta foi capturada.
- país (string): Código de 2 letras do país do usuário. A lista de códigos de país pode ser encontrada aqui https://www.iso.org/iso-3166-country-codes.html
- created_time (datetime): O horário de envio da resposta no formato rfc3339.
- dispositivo (string): O tipo de dispositivo usado para enviar a resposta. Pode ser um dos valores "tablet", "mobile", "desktop"
- hotjar_user_id (string): Um identificador único para o usuário que enviou a resposta
- is_complete (boolean): Sinalizador indicando se a resposta está concluída ou não.
- so (string): O sistema operacional do usuário.
- recording_url (string): Um link para a Gravação do Hotjar que contém essa resposta, se existir.
- response_origin_url (string): A URL do site onde o usuário enviou a resposta.
- user_attributes (lista de Atributos do Usuário): Uma lista de atributos do usuário fornecidos pela API de Identificação do Hotjar. Cada Atributo do Usuário contém os seguintes campos:
- nome (string): O nome do atributo do usuário
- valor (string/inteiro/flutuante/booleano/datetime): O valor do atributo do usuário
- tamanho_da_janela: O tamanho da janela do navegador do usuário. Contém os seguintes campos:
- largura (inteiro): A largura da janela, se existir.
- altura (inteiro): A altura da janela, se existir.
- próximo_cursor (string): O cursor para a próxima página.
Resposta de exemplo:
{
"next_cursor": "gAAAAABj91CIjMAhTxEHLEyeycuAsTylGzwlaKMIo5lBl_zKikJeO3DQa9hvsChE2Kc032DlDne0HE7xURLuyFTDWWaiBZoob0wCLhb39eCotgBKNW5vodsXEVIrNT0nX_X5kdziNDup",
"results": [
{
"answers": [
{
"answer": "Amei o seu produto.",
"comment": "Eu uso todos os dias.",
"question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
"tags": [
{
"name": "todo"
},
{
"name": "positive"
}
],
"sentiment": "positive"
},
{
"answer": "10",
"comment": null,
"question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
"tags": [],
"sentiment": null
}
],
"browser": "Navegador Mobile Safari UI/WKWebView",
"country": "mt",
"created_time": "2023-02-23T11:39:51.473Z",
"device": "desktop",
"hotjar_user_id": "8c9edf6f-ff84-3f2b-9755-15bbfff75aaf",
"id": "response_f8ccb724-8110-48d0-8715-2138be7a9c06",
"is_complete": false,
"os": "iOS",
"recording_url": null,
"response_origin_url": "https://www.example.com/484845acc8164763ba6d",
"user_attributes": [
{
"name": "customer_type",
"value": "enterprise"
}
],
"window_size": {
"height": 768,
"width": 1024
}
}
]
}
Exemplo de carga útil para diferentes tipos de Perguntas de Pesquisa:
reaction
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
"type": "reaction",
"text": "Como você avalia a sua experiência?",
"is_required": true,
"labels": {
"low_label": "Nada bom",
"high_label": "Excelente!"
}
}
short-text
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
"type": "short-text",
"text": "Você gosta do nosso novo layout?",
"is_required": true
}
long-text
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
"type": "long-text",
"text": "O que você gosta no novo layout?",
"is_required": false
}
single-option
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
"type": "single-option",
"text": "Você usaria nosso site novamente?",
"is_required": true,
"choices": [
{
"text": "Sim",
"allow_comment": false
},
{
"text": "Não",
"allow_comment": false
},
{
"text": "Não sei",
"allow_comment": false
}
]
}
multiple-option
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
"type": "multiple-option",
"text": "Nos diga o que você mais gosta",
"is_required": false,
"choices": [
{"text": "A User Experience", "allow_comment": false},
{"text": "Os recursos", "allow_comment": false},
{"text": "Outro", "allow_comment": true}
]
}
rating-1-5
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef08",
"type": "rating-1-5",
"text": "De 1 a 5, o quanto você gosta do nosso serviço?",
"is_required": true,
"labels": {"low_label": "Odiei", "high_label": "Amei"}
}
rating-1-7
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef09",
"type": "rating-1-7",
"text": "Avalie sua experiência de 1 a 7.",
"is_required": false,
"labels": {"low_label": "Pior experiência de todas.", "high_label": "Incrível!"}
}
nps
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef10",
"type": "nps",
"text": "Quão provável você é de nos recomendar a um amigo ou colega?",
"is_required": true,
"labels": {"low_label": "Nada provável.", "high_label": "Absolutamente!"}
}
email
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef11",
"type": "email",
"text": "Por favor, insira seu endereço de e-mail caso queira que entremos em contato com você",
"is_required": false
}
obrigado
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef12",
"type": "obrigado",
"text": "Muito obrigado pelas suas respostas!",
"is_required": true
}
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
"type": "declaração",
"text": "Esta pesquisa levará 5 minutos",
"is_required": true
}
Consulta de usuário
Realize uma consulta de usuário (com exclusão opcional)
POST /v1/organizações/:id_da_organização/consulta-de-usuário
-
id_da_organização
: O identificador único da organização. Este ID pode ser encontrado na página Sites e Organizações ao lado da respectiva organização.
Parâmetros do corpo JSON:
As solicitações para este endpoint devem ser enviadas com Content-Type: application/json; charset=utf-8
.
-
email_do_sujeito_dos_dados
: Endereço de e-mail do usuário-alvo. -
mapeamento_de_id_do_site_para_id_do_usuário
: Um mapa (objeto) de entradas <id_do_site> para <id_do_usuário_no_seu_site>, útil quando você usou a API de Atributos do Usuário para enviar o ID único do usuário para nós. -
excluir_todos_os_registros
: Booleano (true/false) indicando se quaisquer dados encontrados devem ser excluídos imediatamente.
Para uma solicitação bem-sucedida, pelo menos um (ou ambos) dos parâmetros email_do_sujeito_dos_dados
e mapeamento_de_id_do_site_para_id_do_usuário
devem ser enviados no corpo da sua solicitação.
Se delete_all_hits
for false
, significando que não iremos excluir automaticamente todos os hits, então um e-mail com um link para o relatório de dados será enviado para o endereço de data_subject_email
e o endereço de destinatário padrão que você especificar na Página de Consulta de Usuário. Isso imita a forma como a ferramenta de Consulta de Usuário funciona através da aplicação web.
Se delete_all_hits
for true
, então nenhum e-mail será enviado para você ou para o sujeito dos dados. Iremos silenciosamente excluir quaisquer dados que encontrarmos.
Solicitação de exemplo:
## Consulta de Usuário
curl -X "POST" "https://api.hotjar.io/v1/organizations//user-lookup" \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"delete_all_hits": false,
"data_subject_email": "text@example.com",
"data_subject_site_id_to_user_id_map": {
"42": "unique_id_42"
}
}'
Resposta de exemplo:
202 Aceitar
, sem dados.