Referência da API do Hotjar

• Visão geral
• Autenticação
• Limites de taxa
• Respostas e erros
• Paginação
• Versionamento

Referência da API

• Respostas da Pesquisa
• Consulta de Usuário

---

Visão Geral

A API do Hotjar é uma API HTTP baseada em JSON:

• É orientado a recursos (como REST)
• Ele aceita corpos de solicitação JSON
• Ele retorna respostas JSON
• Usa verbos HTTP padrão (métodos)
• 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 utiliza 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 a partir 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 de token com o ID do cliente e o segredo do cliente
• Receber em resposta um token temporário de portador
• Enviar o token de portador com todas as outras chamadas de API através do cabeçalho HTTP Authorization

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 entre máquinas, onde a chave de API é mantida em segredo.

Obtendo o token de acesso

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:

1. grant_type deve ser definido como client_credentials
2. client_id deve ser definido como o ID do cliente da sua chave de API
3. 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, é uma resposta de objeto JSON contendo três chaves:

1. token_type que será definido como Bearer
2. expires_in que especifica o número de segundos até que o token de acesso expire
3. access_token que é o próprio token de acesso

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 acesso

Você deve enviar o token de acesso, obtido através do método acima, através do 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_aqui

No caso de suas solicitações não incluírem o cabeçalho, a resposta será 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, a resposta será um código de status HTTP 403.

Voltar ao topo

Limitação de Taxa

Atualmente, a API do Hotjar possui limitação de taxa por endereço de origem e está limitada a 3000 solicitações por minuto (50 por segundo). Pretendemos avaliar restrições adicionais de limitação de taxa no futuro. Se você fizer muitas solicitações, a API responderá com um código de status HTTP 429.

Voltar ao topo

Respostas e Erros

O código de status HTTP é autoritativo; se o código de status estiver na faixa 2XX, a chamada da 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 ponto de extremidade da API retornar dados, eles serão retornados como JSON. Nesses casos, a resposta de nível superior será um objeto JSON (em vez de um array). Se o ponto de extremidade retornar vários objetos (linhas), eles serão enviados como um array sob a chave results. Uma chave de nível superior next_cursor será incluída na resposta para pontos de extremidade 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:

• código - uma string destinada a ser lida por máquinas, contendo o código de erro
• msg - uma string, legível por humanos, explicando a causa do erro.

Voltar ao topo

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. Ao fazer a primeira solicitação, você receberá na resposta um campo next_cursor. Para obter a próxima página de itens ao fazer 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 há mais resultados, next_cursor é null.

Voltar ao topo

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. No momento, temos apenas uma versão da API (v1) e podemos introduzir outras versões no futuro. Garantiremos que, se decidirmos parar de oferecer suporte a uma versão da API no futuro, daremos pelo menos seis meses de aviso antes de remover o suporte.

Voltar ao topo

Referência da API

Respostas da Pesquisa

Listar Pesquisas

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 na respectiva organização.

Parâmetros de URL (opcional):

• limite: O número de pesquisas a serem retornadas na resposta. Máximo 100.
• cursor: O cursor a ser usado para buscar uma página específica.
• com_perguntas: Sinalizador (verdadeiro/falso) indicando se as informações das perguntas devem ser incluídas na resposta. Por padrão, não são incluídas.

Campos de resposta:

• results: Uma lista de itens de pesquisa. Cada pesquisa contém os seguintes campos:
  • id (string): O identificador único da pesquisa.
  • url (string): A URL da pesquisa para a API do Hotjar.
  • created_time (datetime): O horário de criação da pesquisa no formato rfc3339.
  • is_enabled (boolean): Sinalizador que indica se a pesquisa está habilitada ou não.
  • name (string): O nome da pesquisa.
  • responses_url (string): A URL da API do Hotjar para as respostas desta pesquisa.
  • type (string): O tipo da pesquisa. Pode ser um dos seguintes: link, full_screen ou popover.
  • questions: Uma lista de itens de pergunta. Incluído opcionalmente se a sinalização estiver definida como verdadeira nos parâmetros da solicitação.
    • id (string): O identificador único da pergunta.
    • is_required (boolean): Sinalizador que indica se a pergunta é obrigatória.
    • text (string): O texto da pergunta.
    • type (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): A URL da imagem associada à pergunta, se houver.
    • choices (Lista opcional de objetos Choice): As opções possíveis que os usuários podem selecionar. Este campo será usado apenas para os tipos de pergunta single-option ou multiple-option.
      • text (string): O texto da opção.
      • allow_comment (boolean): Sinalizador que indica se os usuários podem comentar se selecionarem esta opção.
    • labels (Objeto Label opcional): Informações sobre a nomenclatura do rótulo baixo e do rótulo alto. 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.
• 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"
        }
      ]
    }
  ]
}

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 na 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"
    }
  ]
}

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 na respectiva organização.
• survey_id: O identificador único da pesquisa.

Parâmetros de URL (opcional):

• limite: O número de respostas da pesquisa a serem retornadas na resposta. Máximo 100.
• cursor: O cursor a ser usado para buscar uma página específica.

Campos de resposta:

• results: Uma lista de itens de Resposta de Pesquisa. Cada Resposta de Pesquisa contém os seguintes campos:
  • id (string): O identificador único da resposta.
  • answers (lista de objetos Resposta de Pesquisa). Cada Resposta de Pesquisa contém os seguintes campos:
    • question_id (string): O identificador da pergunta.
    • answer (string): A resposta.
    • comment (string): Comentário opcional fornecido pelo usuário.
  • browser (string): O navegador no qual a resposta foi capturada.
  • country (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.
  • device (string): O tipo de dispositivo usado para enviar a resposta. Pode ser qualquer um dos seguintes: "tablet", "mobile", "desktop"
  • hotjar_user_id (string): Um identificador único para o usuário que enviou a resposta.
  • is_complete (boolean): Sinalizador que indica se a resposta está completa ou não.
  • os (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:
    • name (string): O nome do atributo do usuário
    • value (string/integer/float/boolean/datetime): O valor do atributo do usuário
  • window_size: O tamanho da janela do navegador do usuário. Ele contém os seguintes campos:
    • width (integer): A largura da janela.
    • height (integer): A altura da janela.
• next_cursor (string): O cursor para a próxima página.

Resposta de exemplo:

{
  "next_cursor": "gAAAAABj91CIjMAhTxEHLEyeycuAsTylGzwlaKMIo5lBl_zKikJeO3DQa9hvsChE2Kc032DlDne0HE7xURLuyFTDWWaiBZoob0wCLhb39eCotgBKNW5vodsXEVIrNT0nX_X5kdziNDup",
  "results": [
    {
      "answers": [
        {
          "answer": "Eu amo o seu produto.",
          "comment": "Eu uso todos os dias.",
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca"
        },
        {
          "answer": "10",
          "comment": null,
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca"
        }
      ],
      "browser": "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:

reação

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
  "type": "reaction",
  "text": "Como você avaliaria sua experiência?",
  "is_required": true,
  "labels": {
    "low_label": "Nada bom",
    "high_label": "Excelente!"
  }
}

texto-curto

{
  "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
}

opção-única

{
    "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
    "type": "opção-única",
    "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
      }
    ]
  }

opção múltipla

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
  "type": "opção-múltipla",
  "text": "Diga-nos o que você gosta mais",
  "is_required": false,
  "choices": [
    {"text": "A Experiência do Usuário", "allow_comment": false},
    {"text": "Os recursos", "allow_comment": false},
    {"text": "Outro", "allow_comment": true}
  ]
}

classificação-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": "Eu odeio", "high_label": "Eu amo"}
}

classificação-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": "Com certeza!"}
}

email

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef11",
  "type": "email",
  "text": "Por favor, digite 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": "agradecimento",
  "text": "Muito obrigado pelas suas respostas!",
  "is_required": true
}

declaração

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
  "type": "statement",
  "text": "Esta pesquisa levará 5 minutos",
  "is_required": true
}

 

Consulta de Usuário

Realizar uma busca de usuário (com opção de exclusão)

POST /v1/organizações/:id_da_organização/consulta-de-usuário

• organization_id: 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.

• data_subject_email: Endereço de e-mail em formato de string do usuário-alvo.
• data_subject_site_id_to_user_id_map: Um mapa (objeto) de entradas <site_id> para <user_id_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.
• delete_all_hits: Booleano (verdadeiro/falso) indicando se os dados encontrados devem ser excluídos imediatamente.

Para uma solicitação bem-sucedida, pelo menos um (ou ambos) dos campos data_subject_email e data_subject_site_id_to_user_id_map devem ser enviados no corpo da sua solicitação.

Se delete_all_hits for false, o que significa 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 e-mail do data_subject_email e o endereço de destinatário padrão que você especificar na página de Pesquisa de Usuário. Isso imita a forma como a ferramenta de Pesquisa de Usuário funciona através do aplicativo 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.

Exemplo de solicitação:

## 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 Aceito, sem dados.

Voltar ao topo