Référence de l'API Hotjar

• Vue d'ensemble
• Authentification
• Limites de taux
• Réponses et erreurs
• Pagination
• Versioning

Référence de l'API

• Réponses aux enquêtes
• Recherche d'utilisateurs

---

Vue d'ensemble

L'API Hotjar est une API HTTP basée sur JSON :

• Elle est orientée ressources (comme REST)
• Elle accepte des corps de requête JSON
• Elle renvoie des réponses JSON
• Elle utilise des verbes HTTP standard (méthodes)
• Elle utilise des codes d'état HTTP pour communiquer l'état
• Elle utilise le flux de jetons d'authentification OAuth pour l'authentification

Toutes les appels d'API sont effectués sur le même domaine de base : https://api.hotjar.io

Authentification

L'API Hotjar utilise une combinaison de clés API et du flux de jetons d'authentification OAuth pour l'authentification. Vous pouvez générer une clé API depuis dans l'application Hotjar. Les clés API sont composées d'une paire d'éléments : l'identifiant client et le secret client. Lorsque vous souhaitez utiliser l'API, vous devez :

• Envoyer une requête au point de terminaison du jeton avec l'identifiant client et le secret client
• Recevoir en réponse un jeton d'accès temporaire
• Envoyer le jeton d'accès avec toutes les autres appels d'API via l'en-tête HTTP Autorisation

Les clés API accordent l'accès à de nombreux privilèges, vous devez donc les garder secrètes. Ne les partagez pas dans des zones accessibles au public telles que Gitlab ou intégrées dans une application. Les clés API sont destinées à la communication machine à machine, où la clé API est gardée secrète.

Obtention du jeton d'accès

Pour obtenir un jeton d'accès, vous devez envoyer une requête HTTP POST à /v1/oauth/token. La requête doit être encodée en application/x-www-form-urlencoded (c'est une exigence OAuth) et doit inclure trois paramètres :

1. grant_type doit être défini sur client_credentials
2. client_id doit être défini sur l'ID client de votre clé API
3. client_secret doit être défini sur le secret client de votre clé API

Voici un exemple simplifié :

POST /v1/oauth/token HTTP/1.1
Host: api.hotjar.io

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

La réponse, en cas de succès, est un objet JSON contenant trois clés :

1. token_type qui sera défini sur Bearer
2. expires_in qui spécifie le nombre de secondes avant l'expiration du jeton d'accès
3. access_token qui est le jeton d'accès lui-même

Voici un exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"<jeton>",
"token_type":"Bearer",
"expires_in":3600,
}

Utilisation du jeton d'accès

Vous devez envoyer le jeton d'accès, obtenu via la méthode ci-dessus, via l'en-tête HTTP Authorization lors de l'appel des API. La valeur de l'en-tête doit être Bearer <jeton ici>. Voici un exemple simplifié :

GET /v1/sites/1/surveys HTTP/1.1
Host: api.hotjar.io
Authorization: Bearer token_goes_here

Dans le cas où vos requêtes n'incluent pas l'en-tête, une réponse avec un code d'état HTTP de 401 sera renvoyée. Si le jeton est invalide, ou si votre clé API n'a pas l'autorisation d'effectuer l'action demandée, une réponse avec un code d'état HTTP de 403 sera renvoyée.

Retour en haut

Limitation du taux

Actuellement, l'API Hotjar est limitée par adresse source et est limitée à 3000 requêtes par minute (50 par seconde). Nous prévoyons d'évaluer d'autres restrictions de limitation du taux à l'avenir. Si vous effectuez trop de requêtes, l'API répondra avec un code d'état HTTP de 429.

Retour en haut

Réponses et Erreurs

Le code d'état HTTP est autoritaire ; si le code d'état est dans la plage 2XX alors l'appel API a réussi, si le code d'état est dans la plage 4XX alors il y a eu une erreur client, et si le code d'état est dans la plage 5XX alors il y a eu une erreur serveur.

Si le point de terminaison de l'API renvoie des données, elles seront renvoyées sous forme de JSON. Dans ces cas, la réponse de niveau supérieur sera un objet JSON (plutôt qu'un tableau). Si le point de terminaison renvoie plusieurs objets (lignes), ils seront envoyés sous forme de tableau sous une clé results. Une clé de niveau supérieur next_cursor sera incluse dans la réponse pour les points de terminaison avec pagination (voir ci-dessous).

Dans certains cas, lorsqu'une erreur est renvoyée, des informations supplémentaires sur l'erreur seront incluses. Dans ces cas, la réponse sera encodée en JSON et inclura les champs suivants :

• code - une chaîne destinée à être lue par une machine, contenant le code d'erreur
• msg - une chaîne, lisible par l'homme, expliquant la cause de l'erreur.

Retour en haut

Pagination

L'API Hotjar utilise une pagination basée sur le curseur. Lorsqu'un point de terminaison prend en charge la pagination, vous pouvez envoyer un paramètre limit pour spécifier le nombre d'éléments que vous souhaitez recevoir. Lorsque vous effectuez la première requête, vous recevrez dans la réponse un champ next_cursor. Pour obtenir la page suivante des éléments lors de la prochaine requête, transmettez la valeur de next_cursor en tant que paramètre appelé cursor. L'API utilise ensuite cette valeur pour renvoyer la page suivante des éléments. Lorsqu'il n'y a pas de résultats supplémentaires, next_cursor est null.

Retour en haut

Versioning

L'API Hotjar utilise un numéro de version "global" plutôt que chaque point de terminaison individuel étant versionné. Nous n'introduirons pas de modifications rétrocompatibles au sein d'une version. À l'heure actuelle, nous n'avons qu'une seule version d'API (v1) et pourrions introduire d'autres versions à l'avenir. Nous veillerons à ce que si, à l'avenir, nous décidons de cesser de prendre en charge une version de l'API, nous donnerons au moins six mois de préavis avant de supprimer le support.

Retour en haut

Référence de l'API

Réponses aux enquêtes

Liste des enquêtes

GET /v1/sites/:site_id/surveys

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans la page Sites & Organizations sous l'organisation respective.

Paramètres d'URL (optionnels) :

• limit: Le nombre d'enquêtes à renvoyer dans la réponse. Maximum 100.
• cursor: Le curseur à utiliser pour récupérer une page spécifique.
• with_questions: Drapeau (true/false) indiquant si les informations sur les questions doivent être incluses dans la réponse. Par défaut, elles ne le sont pas.

Champs de réponse :

• résultats : Une liste d'éléments d'enquête. Chaque enquête contient les champs suivants :
  • id (chaîne de caractères) : L'identifiant unique de l'enquête.
  • url (chaîne de caractères) : L'URL de l'enquête pour l'API Hotjar.
  • created_time (datetime) : L'heure de création de l'enquête au format rfc3339.
  • updated_time (datetime) : L'heure de mise à jour de l'enquête au format rfc3339.
  • is_enabled (booléen) : Indicateur indiquant si l'enquête est activée ou non.
  • name (chaîne de caractères) : Le nom de l'enquête.
  • responses_url (chaîne de caractères) : L'URL de l'API Hotjar pour les réponses de cette enquête.
  • type (chaîne de caractères) : Le type de l'enquête. Il peut être l'un des suivants : link, full_screen ou popover.
  • questions : Une liste d'éléments de question. Inclus en option si le drapeau est défini sur vrai dans les paramètres de la requête.
    • id (chaîne de caractères) : L'identifiant unique de la question.
    • is_required (booléen) : Indicateur indiquant si la question est obligatoire.
    • text (chaîne de caractères) : Le texte de la question.
    • type (chaîne de caractères) : Le type de la question. Les valeurs possibles sont reaction, long-text, short-text, single-option, multiple-option, email, rating-1-5, rating-1-7, nps, statement et thank-you.
    • image_url (url facultative) : L'URL de l'image associée à la question, s'il y en a une.
    • choices (liste facultative d'objets de choix) : Les choix possibles que les utilisateurs peuvent sélectionner. Ce champ ne sera utilisé que pour les types de questions single-option ou multiple-option.
      • text (chaîne de caractères) : Le texte du choix
      • allow_comment (booléen) : Indicateur indiquant si les utilisateurs peuvent commenter s'ils sélectionnent ce choix.
    • labels (objet Label facultatif) : Informations sur la dénomination de l'étiquette basse et de l'étiquette haute. Ce champ ne sera utilisé que pour les types de questions rating-1-5, rating-1-7, nps et reaction.
      • low_label (chaîne de caractères) : La dénomination de l'option de score le plus bas pour la question.
      • high_label (chaîne de caractères) : La dénomination de l'option de score le plus élevé pour la question.
  • sentiment_analysis_enabled (booléen) : Indique si les réponses passent par l'analyse de sentiment ou non.
• next_cursor (chaîne de caractères) : Le curseur pour la page suivante.

Réponse d'exemple :

{
  "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": "Nom de mon enquête",
      "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": "Que pensez-vous de notre API?",
          "type": "long-text"
        }
      ],
      "sentiment_analysis_enabled": false
    }
  ]
}

Récupérer l'enquête

GET /v1/sites/:site_id/surveys/:survey_id

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans la page Sites & Organisations sous l'organisation respective.
• survey_id: L'identifiant unique de l'enquête.

Champs de réponse :

Les champs de réponse sont les mêmes que l'élément Enquête décrit dans le point de terminaison List Surveys ci-dessus. Les questions sont toujours incluses dans ce point de terminaison.

Réponse d'exemple :

{
  "created_time": "2023-02-23T11:08:53.287Z",
  "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "is_enabled": false,
  "name": "Nom de mon enquête",
  "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": "Que pensez-vous de notre API?",
      "type": "long-text"
    }
  ],
  "sentiment_analysis_enabled": true
}

Lister les réponses de l'enquête

GET /v1/sites/:site_id/surveys/:survey_id/responses

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans la page Sites & Organisations sous l'organisation respective.
• survey_id: L'identifiant unique de l'enquête.

Paramètres d'URL (optionnels) :

• limit: Le nombre de réponses d'enquête à renvoyer dans la réponse. Maximum 100.
• cursor: Le curseur à utiliser pour récupérer une page spécifique.

Champs de réponse :

• résultats : Une liste d'éléments de réponse au sondage. Chaque réponse au sondage contient les champs suivants :
  • id (chaîne) : L'identifiant unique de la réponse.
  • answers (liste d'objets de réponse au sondage). Chaque réponse au sondage contient les champs suivants :
    • question_id (chaîne) : L'identifiant de la question.
    • answer (chaîne) : La réponse.
    • commentaire (chaîne) : Commentaire facultatif fourni par l'utilisateur.
    • tags (liste d'objets d'étiquette de réponse au sondage). Chaque étiquette de réponse au sondage contient les champs suivants :
      • name (chaîne) : Le nom de l'étiquette.
    • sentiment (chaîne) : Le sentiment du texte de la réponse. Il peut être "positif", "négatif", "neutre" ou `null`. La valeur null est définie pour les réponses non textuelles ou lorsque aucun sentiment n'a été défini. La clé de sentiment ne sera présente que si elle fait partie de votre plan produit Ask.
      
  • navigateur (chaîne) : Le navigateur sur lequel la réponse a été capturée.
  • pays (chaîne) : Code à 2 lettres du pays de l'utilisateur. La liste des codes de pays peut être trouvée ici https://www.iso.org/iso-3166-country-codes.html
  • created_time (datetime) : L'heure de soumission de la réponse au format rfc3339.
  • appareil (chaîne) : Le type d'appareil utilisé pour soumettre la réponse. Il peut s'agir de "tablette", "mobile", "ordinateur de bureau"
  • hotjar_user_id (chaîne) : Un identifiant unique pour l'utilisateur ayant soumis la réponse.
  • is_complete (booléen) : Indicateur indiquant si la réponse est complète ou non.
  • système d'exploitation (chaîne) : Le système d'exploitation de l'utilisateur.
  • recording_url (chaîne) : Un lien vers l'enregistrement Hotjar qui contient cette réponse, s'il existe.
  • response_origin_url (chaîne) : L'URL du site où l'utilisateur a soumis la réponse.
  • user_attributes (liste d'attributs utilisateur) : Une liste d'attributs de l'utilisateur fournis par l'API Hotjar Identify. Chaque attribut utilisateur contient les champs suivants :
    • name (chaîne) : Le nom de l'attribut utilisateur
    • valeur (chaîne/entier/décimal/booléen/datetime) : La valeur de l'attribut utilisateur
  • window_size : La taille de la fenêtre du navigateur de l'utilisateur. Il contient les champs suivants :
    • largeur (entier) : La largeur de la fenêtre, si elle existe.
    • hauteur (entier) : La hauteur de la fenêtre, si elle existe.
• next_cursor (chaîne) : Le curseur pour la page suivante.

Exemple de réponse :

{
  "next_cursor": "gAAAAABj91CIjMAhTxEHLEyeycuAsTylGzwlaKMIo5lBl_zKikJeO3DQa9hvsChE2Kc032DlDne0HE7xURLuyFTDWWaiBZoob0wCLhb39eCotgBKNW5vodsXEVIrNT0nX_X5kdziNDup",
  "results": [
    {
      "answers": [
        {
          "answer": "J'adore votre produit.",
          "comment": "Je l'utilise tous les jours.",
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [
            {
              "name": "à faire"
            },
            {
              "name": "positif"
            }
          ],
          "sentiment": "positif"
        },
        {
          "answer": "10",
          "comment": null,
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [],
          "sentiment": null
        }
      ],
      "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": "type_client",
          "value": "entreprise"
        }
      ],
      "window_size": {
        "height": 768,
        "width": 1024
      }
    }
  ]
}

Exemple de charge utile pour différents types de questions de sondage :

réaction

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
  "type": "réaction",
  "text": "Comment évalueriez-vous votre expérience ?",
  "is_required": true,
  "labels": {
    "low_label": "Pas du tout bon",
    "high_label": "Excellent !"
  }
}

texte-court

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
  "type": "texte-court",
  "text": "Aimez-vous notre nouveau design ?",
  "is_required": true
}

texte-long

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
  "type": "texte-long",
  "text": "Qu'aimez-vous dans le nouveau design ?",
  "is_required": false
}

option-simple

{
    "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
    "type": "option-simple",
    "text": "Utiliseriez-vous à nouveau notre site ?",
    "is_required": true,
    "choices": [
      {
        "text": "Oui",
        "allow_comment": false
      },
      {
        "text": "Non",
        "allow_comment": false
      },
      {
        "text": "Je ne sais pas",
        "allow_comment": false
      }
    ]
  }

option-multiple

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
  "type": "option-multiple",
  "text": "Dites-nous ce que vous aimez le plus",
  "is_required": false,
  "choices": [
    {"text": "L'expérience utilisateur", "allow_comment": false},
    {"text": "Les fonctionnalités", "allow_comment": false},
    {"text": "Autre", "allow_comment": true}
  ]
}

notation-1-5

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef08",
  "type": "notation-1-5",
  "text": "De 1 à 5, à quel point aimez-vous notre service ?",
  "is_required": true,
  "labels": {"low_label": "Je déteste", "high_label": "J'adore"}
}

notation-1-7

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef09",
  "type": "rating-1-7",
  "text": "Évaluez votre expérience de 1 à 7.",
  "is_required": false,
  "labels": {"low_label": "Pire expérience jamais vécue.", "high_label": "Incroyable!"}
}

nps

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef10",
  "type": "nps",
  "text": "À quel point êtes-vous susceptible de nous recommander à un ami ou un collègue?",
  "is_required": true,
  "labels": {"low_label": "Pas du tout probable.", "high_label": "Absolument!"}
}

email

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef11",
  "type": "email",
  "text": "Veuillez saisir votre adresse e-mail au cas où vous souhaiteriez que nous vous contactions",
  "is_required": false
}

merci

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef12",
  "type": "thank-you",
  "text": "Merci beaucoup pour vos réponses!",
  "is_required": true
}

déclaration

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
  "type": "statement",
  "text": "Ce sondage vous prendra 5 minutes",
  "is_required": true
}

 

Recherche d'utilisateur

Effectuer une recherche d'utilisateur (avec suppression facultative)

POST /v1/organizations/:organization_id/user-lookup

• organization_id: L'identifiant unique de l'organisation. Cet ID peut être trouvé dans la page Sites & Organisations à côté de l'organisation respective.

Paramètres du corps JSON:

Les requêtes à ce point d'extrémité doivent être envoyées avec Content-Type: application/json; charset=utf-8.

• data_subject_email: Adresse e-mail en chaîne du utilisateur cible.
• data_subject_site_id_to_user_id_map: Une carte (objet) des entrées <site_id> à <user_id_sur_votre_site>, utile lorsque vous avez utilisé l'API Attributs de l'utilisateur pour nous envoyer l'identifiant unique de l'utilisateur.
• delete_all_hits: Booléen (true/false) indiquant si les données trouvées doivent être immédiatement supprimées.

Pour une requête réussie, au moins un (ou les deux) de data_subject_email et data_subject_site_id_to_user_id_map doivent être envoyés dans le corps de votre requête.

Si delete_all_hits est false, ce qui signifie que nous ne supprimerons pas automatiquement toutes les données, un e-mail contenant un lien vers le rapport de données sera envoyé à l'adresse data_subject_email et à l'adresse du destinataire par défaut que vous spécifiez dans la page de recherche d'utilisateur. Cela imite le fonctionnement de l'outil de recherche d'utilisateur via l'application web.

Si delete_all_hits est true, alors aucun e-mail ne vous sera envoyé ni à la personne concernée. Nous supprimerons silencieusement toutes les données que nous trouverons.

Exemple de requête :

## Recherche d'utilisateur
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"
}
}'

Exemple de réponse :

202 Accepté, sans données.

Retour en haut