Référence de l'API Réponses pour les sondages

• Aperçu
• Comment générer et supprimer des identifiants API
• Authentification
• Limites de taux
• Réponses et erreurs
• Pagination
• Versionnage

Référence API

• Réponses au sondage
• Recherche de l’utilisateur

Aperçu

L'API Réponses 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
• Utilise des verbes HTTP standard (méthodes)
• Utilise des codes d'état HTTP pour communiquer le statut
• Utilise le flux d'identifiants client OAuth pour l'authentification

Tous les appels API sont effectués vers le même domaine de base : https://api.hotjar.io

Retour en haut

Comment générer et supprimer des identifiants API

Génération d'identifiants API

1. Visitez votre page API.

2. Sélectionnez l'Organisation pour les identifiants API.

3. Entrez un Nom d'identifiant.

4. Sélectionnez le Domaine pour les identifiants API afin de limiter la portée de la fonctionnalité.

Cliquez sur 'Générer des identifiants'.

Les identifiants générés précédemment seront affichés sur la page API.

Suppression des identifiants API

1. Visitez votre page API.

2. Identifiez les identifiants API pertinents à supprimer.

3. Cliquez sur 'Supprimer des identifiants'.

Cela supprimera les identifiants API générés.

Retour en haut

Authentification

L'API Réponses utilise une combinaison de clés API et du flux d'identifiants client OAuth pour l'authentification. Vous pouvez générer une clé API depuis la page API Voice of Customer. Les clés API sont composées d'une paire d'articles : l'ID client et la clé secrète client. Lorsque vous souhaitez utiliser l'API, vous devez :

• Envoyer une requête à l'endpoint de jeton avec l'ID client et la clé secrète client
• Recevoir en réponse un jeton d'accès temporaire
• Envoyer le jeton d'accès avec tous les autres appels API via l'en-tête HTTP Authorization

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 tant que 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 la clé secrète 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, si elle est réussie, 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 jusqu'à 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":"<token>",
"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 <token 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, alors elle répondra avec un code d'état HTTP de 401. Si le jeton est non valide, ou si votre clé API n'a pas la permission d'effectuer l'action demandée, alors elle répondra avec un code d'état HTTP de 403.

Retour en haut

Limitation de taux

Actuellement, l'API Réponses est limitée par adresse source et est limitée à 3000 requêtes par minute (50 par seconde). 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 gamme 2XX, alors l'appel API a réussi, si le code d'état est dans la gamme 4XX, alors il y a eu une erreur client, et si le code d'état est dans la gamme 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 au format 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é next_cursor de niveau supérieur 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 lisible par 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 Réponses 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 combien d'articles vous souhaitez recevoir. Lorsque vous effectuez la première demande, vous recevrez dans la réponse un champ next_cursor. Pour obtenir la prochaine page d'articles lorsque vous effectuez la demande suivante, passez la valeur de next_cursor comme paramètre appelé cursor. L'API utilise ensuite cette valeur pour renvoyer la prochaine page d'articles. Lorsqu'il n'y a pas de résultats supplémentaires, next_cursor est null.

Retour en haut

Versionnage

L'API Réponses utilise un numéro de version "mondial" plutôt que chaque point de terminaison individuel soit versionné. Nous n'introduirons pas de changements incompatibles avec les versions précédentes au sein d'une version. Actuellement, nous n'avons qu'une seule version de l'API (v1) et nous pourrions introduire d'autres versions à l'avenir. Nous veillerons à ce que si, à l'avenir, nous décidons d'arrêter de prendre en charge une version de l'API, nous donnerons un préavis d'au moins six mois avant de retirer le support.

Retour en haut

Référence API

Réponses aux Sondages

Lister les Sondages

Lors de la liste des réponses aux sondages, les réponses sont triées par date de création dans l'ordre décroissant. Cela signifie que les réponses les plus récentes sont affichées en premier. À ce moment, il n'est pas possible de filtrer les réponses, par exemple, en filtrant les réponses d'une date spécifique.

GET /v1/sites/:site_id/surveys

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans l'URL lors de la consultation de votre page Sondages - https://insights.hotjar.com/sites/{site_id}/surveys/list.

Paramètres URL (optionnel) :

• limit: Le nombre de sondages à renvoyer dans la réponse. Maximum 100.
• cursor: Le curseur à utiliser pour récupérer une page spécifique. 
• with_questions: Indicateur (vrai/faux) indiquant si les informations sur les questions doivent être incluses dans la réponse. Par défaut, elles ne sont pas incluses.

Champs de réponse :

• résultats : Une liste d'articles de sondage. Chaque sondage contient les champs suivants :
  • id (chaîne) : L'identifiant unique du sondage.
  • url (chaîne) : L'URL du sondage pour l'API Réponses.
  • created_time (datetime) : La date de création du sondage au format rfc3339.
  • updated_time (datetime) : La date de mise à jour du sondage au format rfc3339.
  • is_enabled (booléen) : Indicateur indiquant si le sondage est activé ou non.
  • nom (chaîne) : Le nom du sondage.
  • responses_url (chaîne) : L'URL de l'API Réponses pour les réponses de ce sondage
  • type (chaîne) : Le type du sondage. Il peut être l'un de lien, plein écran, ou bulle contextuelle.
  • questions : Une liste d'articles de question. Inclus optionnellement si le drapeau est défini sur vrai dans les paramètres de la requête.
    • id (chaîne) : L'identifiant unique de la question.
    • is_required (booléen) : Indicateur indiquant si la question est obligatoire.
    • text (chaîne) : Le texte de la question.
    • type (chaîne) : Le type de la question. Les valeurs possibles sont réaction,texte long, texte court, option unique, options multiples e-mail, évaluation-1-5, évaluation-1-7, nps, déclaration, et merci.
    • image_url (URL optionnelle) : L'URL de l'image associée à la question, s'il y en a une.
    • choices (Liste optionnelle d'objets Choice) : Les choix possibles que les utilisateurs peuvent sélectionner. Ce champ ne sera utilisé que pour les types de questions option unique ou options multiples.
      • text (chaîne) : Le texte du choix
      • allow_comment (booléen) : Indicateur indiquant si les utilisateurs peuvent commenter s'ils sélectionnent ce choix.
    • labels (Objet Label optionnel) : Informations sur la nomination de l'étiquette faible et de l'étiquette élevée. Ce champ ne sera utilisé que pour les types de questions évaluation-1-5, évaluation-1-7, nps, et réaction.
      • low_label (chaîne) : La nomination pour l'option de score la plus basse pour la question.
      • high_label (chaîne) : La nomination pour l'option de score la plus élevée pour la question.
  • sentiment_analysis_enabled (booléen) : Indique si les réponses passent par l'analyse des sentiments ou non.
• next_cursor (chaîne) : Le curseur pour la page suivante.

Exemple de réponse :

{
  "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": "Mon nom de sondage",
      "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 le sondage

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

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans l'URL lors de la consultation de votre page Sondages - https://insights.hotjar.com/sites/{site_id}/surveys/list .
• survey_id: L'identifiant unique du sondage.

Champs de réponse :

Les champs de réponse sont les mêmes que ceux de l'article Sondage décrits dans le point de terminaison Liste des sondages ci-dessus. Les questions sont toujours incluses dans ce point de terminaison.

Exemple de réponse :

{
  "created_time": "2023-02-23T11:08:53.287Z",
  "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "is_enabled": false,
  "name": "Mon nom de sondage",
  "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 au sondage

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

• site_id: L'identifiant unique du site. Cet ID peut être trouvé dans l'URL lors de la consultation de votre page Sondages - https://insights.hotjar.com/sites/{site_id}/surveys/list .
• survey_id: L'identifiant unique du sondage.

Paramètres d'URL (optionnel) :

• limit: Le nombre de réponses au sondage à retourner 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'articles de réponse au sondage. Chaque réponse au sondage contient les champs suivants :
  • id (chaîne) : L'identifiant unique de la réponse.
  • réponses (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
    • réponse (chaîne) : La réponse.
    • commentaire (chaîne) : Commentaire optionnel fourni par l'utilisateur.
    • étiquettes (liste d'objets d'étiquette de réponse au sondage). Chaque étiquette de réponse au sondage contient les champs suivants :
      • nom (chaîne) : Le nom de l'étiquette.
    • sentiment (chaîne) : Le sentiment du texte de la réponse. Il peut être l'un des suivants : "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 offre 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 indicatifs téléphoniques internationaux peut être trouvée ici https://www.iso.org/iso-3166-country-codes.html
  • created_time (datetime) : L'heure d'envoi de la réponse au format rfc3339.
  • device (chaîne) : Le type de dispositif utilisé pour soumettre la réponse. Cela peut être l'un des suivants : "tablette", "mobile", "desktop"
  • hotjar_user_id (chaîne) : Un identifiant unique pour l'utilisateur qui a soumis la réponse
  • is_complete (booléen) : Indicateur indiquant si la réponse est complétée ou non.
  • os (chaîne) : Le système d'exploitation de l'utilisateur.
  • recording_url (chaîne) : Un lien vers l'enregistrement qui contient cette réponse, si elle 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 des attributs de l'utilisateur fournis par l'API d’Identification. Chaque attribut utilisateur contient les champs suivants :
    • nom (chaîne) : Le nom de l'attribut utilisateur
    • valeur (chaîne/entier/flottant/booléen/datetime) : La valeur de l'attribut utilisateur
  • window_size : La taille de la fenêtre du navigateur de l'utilisateur. Elle 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": "todo"
            },
            {
              "name": "positive"
            }
          ],
          "sentiment": "positive"
        },
        {
          "answer": "10",
          "comment": null,
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [],
          "sentiment": null
        }
      ],
      "browser": "Mobile Safari IU/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
      }
    }
  ]
}

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

reaction

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

short-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
  "type": "short-text",
  "text": "Aimez-vous notre nouvelle mise en page ?",
  "is_required": true
}

long-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
  "type": "long-text",
  "text": "Qu'est-ce que vous aimez dans la nouvelle mise en page ?",
  "is_required": false
}

single-option

{
    "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
    "type": "single-option",
    "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
      }
    ]
  }

multiple-option

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
  "type": "multiple-option",
  "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}
  ]
}

rating-1-5

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

rating-1-7

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

nps

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef10",
  "type": "nps",
  "text": "Quelle est la probabilité que vous nous recommandiez à un ami ou 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 entrer votre adresse e-mail au cas où vous voudriez que nous vous contactions",
  "is_required": false
}

thank-you

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

statement

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

Recherche de l’utilisateur

Effectuer une recherche d’utilisateur (avec suppression optionnelle)

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

• organization_id: L'identifiant unique de l'entreprise.

Paramètres du corps JSON :

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

• data_subject_email: Chaîne d'adresse e-mail de l'utilisateur cible.
• data_subject_site_id_to_user_id_map: Une carte (objet) des entrées <site_id> à <user_id_on_your_site>, utile lorsque vous avez utilisé l’API des caractéristiques de l’utilisateur pour nous envoyer l’ID unique de l’utilisateur.
• delete_all_hits: Booléen (vrai/faux) 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 tous les hits, alors un e-mail avec 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 de l’utilisateur. Cela imite le fonctionnement de l'outil de recherche de l’utilisateur à travers l'application web.

Si delete_all_hits est true, alors aucun e-mail ne sera envoyé à vous ou au sujet des données. Nous supprimerons silencieusement toutes les données que nous trouvons.

Exemple de requête :

## Recherche de l’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 Accepted, with no data.

Retour en haut