Référence de l'API des événements

L'API d'événements de Hotjar vous permet d'envoyer des événements à Hotjar en utilisant JavaScript lorsque des actions spécifiques se produisent sur votre site, les enregistrant dans Hotjar en tant qu'Événements. Ces événements peuvent être utilisés pour vous aider à filtrer les données de Enregistrements et de Cartes thermiques, et pour déclencher la capture de session pour démarrer ou faire apparaître les widgets de retour et les enquêtes. 

• Aperçu
• L'appel à l'API d'événements
• Exemples d'appels à l'API d'événements
• Meilleures pratiques
• Tester les événements

---

Aperçu

Les événements Hotjar représentent les actions qu'un utilisateur a effectuées sur votre site. Ces événements sont définis et transmis à Hotjar via le code côté client grâce à l'API des événements Hotjar. Cette API est disponible sur toutes les pages contenant le Code de suivi Hotjar.

Avec JavaScript, vous pouvez définir vos propres critères pour déterminer quel type d'action déclenche l'envoi d'un événement à Hotjar. L'événement peut être envoyé dès le chargement de la page, lorsqu'une modale apparaît, ou lorsqu'ils voient une variation spécifique du contenu à travers un test A/B.

Par exemple, il peut être utile de suivre les utilisateurs qui ont ajouté avec succès une carte de crédit lors d'un processus de paiement en ajoutant un événement tel que Ajout de carte de crédit réussi. Vous pourriez également être intéressé par la comparaison des sessions où une carte de crédit n'a pas été ajoutée avec succès en ajoutant un deuxième événement, tel que Ajout de carte de crédit échoué. En transmettant des événements basés sur les actions des utilisateurs, vous pouvez filtrer les Enregistrements par les utilisateurs qui ont déclenché chaque type d'événement lors de leur processus de paiement. La configuration de ces événements dans le code de votre site pourrait ressembler à ceci :

fetch('/api/ajouter-carte-de-credit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
    hj('event', 'Ajout de carte de crédit réussi')
    // gérer la réponse du backend.
  }
)
.catch(error => {
  hj('event', 'Ajout de carte de crédit échoué')
})

*Consultez vos propres développeurs pour déterminer le code nécessaire pour votre site.

Étant donné que les critères d'envoi des événements sont basés sur votre propre code, la fonctionnalité est très flexible mais nécessitera une programmation personnalisée de la part de votre développeur web.

Retour en haut

L'appel à l'API des événements

Voici le format de base pour un appel à l'API des événements :

hj('event', 'nom_action');

• Le premier paramètre doit toujours contenir la valeur de chaîne event.
• Le deuxième paramètre est le nom personnalisé attribué à votre événement. Dans l'exemple ci-dessus, le nom de l'événement est nom_action, mais cela peut être ce que vous choisissez. (Exemple : 'ouverture_modale', 'affichage_variant_a', etc.)

Soyez conscient des limitations lors de la mise en œuvre des événements

• Nommer vos événements.

  Le nom de l'événement ne doit pas dépasser 250 caractères et ne peut contenir que des caractères alphanumériques (a-z, A-Z, 0-9), des espaces, des tirets bas (_), des tirets (-), des points (.), des deux-points (:) et des barres obliques (/).

• Limite de 10 000 événements uniques par site Hotjar.

  Les filtres Hotjar ne prendront en charge que 10 000 événements uniques par site Hotjar, avec un nombre illimité d'utilisateurs associés à ces événements. Si vous dépassez cette limite, seuls les 10 000 événements les plus utilisés (classés de 0 à 9, a-Z) seront consultables dans l'interface. Il s'agit d'un total roulant, donc une fois la limite dépassée, certains événements existants peuvent devenir non consultables dans le filtre. Si vous dépassez la limite, vous pouvez supprimer des enregistrements contenant des événements dont vous n'avez plus besoin. Environ 10 minutes après la suppression, votre liste de filtres d'événements se rafraîchira.

• Seuls les 50 premiers événements uniques dans une seule session seront consultables par les filtres.
  Pour optimiser les performances, Hotjar évaluera uniquement les 50 premiers événements uniques dans une session pour déterminer si une session correspond aux critères du filtre d'événements. Cela signifie que si une session contient 51 événements uniques, le dernier événement unique déclenché pendant la session ne sera pas détecté si vous filtrez les enregistrements en fonction de cet événement. Cependant, les 51 événements seront toujours visibles dans la vue de lecture des enregistrements de chaque session.

• Il n'est actuellement pas possible de transmettre des propriétés d'événement avec l'événement.

Retour en haut

Exemples d'appels API d'événements

Voici quelques exemples d'utilisation des événements.

• Envoyez un événement à Hotjar que vous pouvez utiliser pour déclencher une enquête lorsque l'utilisateur clique sur un bouton S'abonner.

  hj('event', 'abonnement_liste_email');
  

• Envoyez un événement à Hotjar lié à une erreur spécifique, afin de pouvoir filtrer vos enregistrements par utilisateurs ayant rencontré une erreur lors de leur session.

  hj('event', 'erreur_survenue');
  

• Envoyez un événement à Hotjar pour vous informer quand un utilisateur charge une variante de page spécifique lors d'un test A/B.

  hj('event', 'affichage_variant_b');

Retour en haut

Meilleures pratiques

• Ne transmettez pas d'informations d'identification personnelle en tant qu'événement.

  Les informations d'identification personnelle (IIP) ne doivent jamais être utilisées comme événements dans Hotjar. Si vous souhaitez connecter les données de session à des utilisateurs spécifiques, vous devriez explorer la fonctionnalité des Attributs Utilisateur à la place.

• Si vous effectuez également des appels d'API d'identification, ceux-ci doivent être exécutés avant les appels d'API d'événements.

  Vous voudrez peut-être combiner les événements avec le ciblage basé sur les Attributs Utilisateur pour déclencher des Enquêtes ou des Retours. Pour configurer cela, l'ordre d'exécution nécessite que l'appel d'API d'identification se produise avant l'appel d'API d'événement, en gardant à l'esprit les appels asynchrones à d'autres services. Si l'appel d'API d'événement est exécuté avant que l'appel d'API d'identification ne soit terminé, le widget Enquête ou Retour ne s'affichera pas.

• Les événements ne peuvent pas être utilisés pour collecter des adresses e-mail ou IP, ou des chiffres avec 9 chiffres ou plus.

  Comme il n'y a actuellement aucun moyen d'utiliser notre outil de recherche d'utilisateur avec des événements, ils ne peuvent pas être utilisés pour collecter des adresses e-mail, des adresses IP ou des chiffres avec 9 chiffres ou plus pour éviter que des numéros de carte de crédit ne soient transmis à Hotjar. Cette décision est basée sur le Règlement Général sur la Protection des Données (RGPD). Si vous souhaitez collecter des adresses e-mail avec le consentement de votre utilisateur et en conformité avec le RGPD, vous pouvez le faire avec les Attributs Utilisateur.

• Le code de suivi Hotjar doit être chargé avant d'envoyer des événements.

  L'objet hj() ne peut pas être accédé tant que le code de suivi Hotjar n'a pas été exécuté sur la page. Si le script appelant l'API d'événements est ajouté avant votre code de suivi Hotjar, une erreur se produira et l'événement ne sera pas reconnu. Si, pour une raison quelconque, l'API d'événement est accédée avant que le code de suivi Hotjar ne soit exécuté, vous pouvez ajouter la ligne de code suivante avant que le code de l'API d'événement ne soit appelé :

  window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments);};

• Pour les sites de commerce électronique, évitez d'envoyer des informations spécifiques sur les produits.

  Cela inclut des informations telles que les codes SKU. En général, les URL sont plus utiles et sont capturées par défaut.

• Soyez prudent lorsque vous envoyez des valeurs à partir d'objets tels que les couches de données GTM.

  Celles-ci contiennent souvent plus de données que vous ne le pensez.

• Évitez de transmettre des éléments tels que des dates ou des horodatages.
• Évitez de transmettre des éléments à partir d'URL tels que des codes de parrainage.
• Évitez de transmettre des journaux d'erreurs détaillés.

Retour en haut

Test des événements

En suivant les étapes ci-dessous, vous pourrez confirmer si vos appels d'API d'événements sont bien reçus par Hotjar. Si vous n'êtes pas familier avec la console de votre navigateur ou les outils de développement, envisagez de faire appel à un membre de votre équipe qui a plus de connaissances sur ces outils ou à un développeur web pour vous aider.

Activez les journaux de débogage Hotjar dans la console de votre navigateur.

Ouvrez la page où vous souhaitez tester l'événement et ajoutez le paramètre ?hjDebug=1 à la fin de l'URL. Voici quelques exemples de ce à quoi cela pourrait ressembler :

https://www.example.com/?hjDebug=1
OU
https://www.example.com/?utm_1234&hjDebug=1

Ouvrez la console de votre navigateur.

Si vous n'êtes pas familier avec les outils de développement de votre navigateur, ou la console, consultez ce guide pour apprendre comment ouvrir la console de votre navigateur.

Déclenchez manuellement l'événement.

Pour déclencher manuellement votre événement, ajoutez le code de l'API d'événement dans la console de votre navigateur et appuyez sur la touche Entrée ou Retour de votre clavier. Si l'événement est déclenché avec succès, vous verrez un journal de confirmation similaire à celui-ci :

Nous vous recommandons également de suivre les étapes que votre utilisateur suivrait pour déclencher l'événement automatiquement. Si l'événement est déclenché automatiquement, vous saurez que votre code est implémenté avec succès.

Si le même événement est détecté lorsqu'il est déclenché manuellement, mais pas automatiquement lors du test du parcours utilisateur, vous devrez peut-être revoir votre code et les critères qui déterminent quand l'appel à l'API d'événement est envoyé.

Retour en haut