- 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
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
Toutes les appels API sont effectués vers le même domaine de base : https://api.hotjar.io
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 les identifiants'.
Cela supprimera les identifiants API générés.
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 :
html- grant_type doit être défini sur client_credentials
- client_id doit être défini sur l'ID client de votre clé API
- 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 :
- token_type qui sera défini sur Bearer
- expires_in qui spécifie le nombre de secondes jusqu'à l'expiration du jeton d'accès
- 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 de l'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.
Limitation de Taux
Actuellement, l'API Réponses est limitée par adresse source et est seulement 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.
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, alors 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é 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.
Pagination
L'API Réponses utilise la pagination basée sur le curseur. Lorsqu'un point de terminaison prend en charge la pagination, vous pouvez envoyer un paramètre limiter 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 page suivante d'articles lorsque vous effectuez la demande suivante, passez la valeur de next_cursor comme paramètre appelé curseur. L'API utilise ensuite cette valeur pour renvoyer la page suivante d'articles. Lorsqu'il n'y a pas de résultats supplémentaires, next_cursor est null.
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.
Référence API
Réponses aux enquêtes
Lister les enquêtes
Lors de la liste des réponses aux enquêtes, 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 jour, 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 Enquêtes - https://insights.hotjar.com/sites/{site_id}/surveys/list.
Paramètres URL (optionnel) :
- limiter: Le nombre d'enquêtes à renvoyer dans la réponse. Maximum 100.
- curseur: 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 :
html- résultats : Une liste d'articles d'enquête. Chaque enquête contient les champs suivants :
- id (chaîne) : L'identifiant unique de l'enquête.
- url (chaîne) : L'URL de l'enquête pour l'API Réponses.
- created_time (datetime) : La date de création de l'enquête au format rfc3339.
- updated_time (datetime) : La date 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.
- nom (chaîne) : Le nom de l'enquête.
- responses_url (chaîne) : L'URL de l'API Réponses pour les réponses de cette enquête
- type (chaîne) : Le type de l'enquête. 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 requise.
- text (chaîne) : Le texte de la question.
- type (chaîne) : Le type de la question. Les valeurs possibles sont réaction,long-texte, court-texte, option-simple, option-multiple, 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 sera utilisé uniquement pour les types de questions option-simple ou option-multiple.
- 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 sera utilisé uniquement 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 d'enquête",
"responses_url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
"type": "bulle contextuelle",
"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 l'URL lors de la consultation de votre page d'enquêtes -
https://insights.hotjar.com/sites/{site_id}/surveys/list. - survey_id: L'identifiant unique de l'enquête.
Champs de réponse :
Les champs de réponse sont les mêmes que l'article d'enquête décrit dans le point de terminaison Liste des enquêtes 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 d'enquête",
"responses_url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
"type": "bulle contextuelle",
"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 à 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 l'URL lors de la consultation de votre page d'enquêtes -
https://insights.hotjar.com/sites/{site_id}/surveys/list. - survey_id: L'identifiant unique de l'enquête.
Paramètres d'URL (optionnel) :
- limit: Le nombre de réponses à l'enquête à retourner dans la réponse. Maximum 100.
- curseur: Le curseur à utiliser pour récupérer une page spécifique.
Champs de réponse :
- résultats : Une liste d'articles de réponse à l'enquête. Chaque réponse à l'enquête contient les champs suivants :
- id (chaîne) : L'identifiant unique de la réponse.
- réponses (liste d'objets de réponse à l'enquête). Chaque réponse à l'enquête 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 à l'enquête). Chaque étiquette de réponse à l'enquête 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 "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.
- appareil (chaîne) : Le type d'appareil utilisé pour soumettre la réponse. Cela peut être l'un de "tablette", "mobile", "ordinateur"
- hotjar_user_id (chaîne) : Un identifiant unique pour l'utilisateur qui a soumis la réponse
- est_complet (booléen) : Indicateur indiquant si la réponse est complétée ou non.
- système (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 cela existe.
- response_origin_url (chaîne) : L'URL du site où l'utilisateur a soumis la réponse.
- attributs_utilisateur (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
- taille_fenêtre : 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 cela existe.
- hauteur (entier) : La hauteur de la fenêtre, si cela 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": "positif"
}
],
"sentiment": "positif"
},
{
"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": "ordinateur",
"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": "entreprise"
}
],
"window_size": {
"height": 768,
"width": 1024
}
}
]
}
Exemple de charge utile pour différents types de questions d'enquête :
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 bon du tout",
"high_label": "Excellent !"
}
}
court-texte
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
"type": "court-texte",
"text": "Aimez-vous notre nouvelle mise en page ?",
"is_required": true
}
long-texte
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
"type": "long-texte",
"text": "Qu'est-ce que vous aimez dans la nouvelle mise en page ?",
"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}
]
}
évaluation-1-5
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef08",
"type": "évaluation-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"}
}
évaluation-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
}
{
"id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
"type": "statement",
"text": "Cette enquête 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: 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 toutes les entrées, alors un e-mail avec un lien vers le rapport de données sera envoyé à l'adresse data_subject_email et à l'adresse 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 à l’utilisateur concerné. 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,
avec aucune donnée.