Vue d'ensemble de l'API du code de suivi

Cette page a été mise à jour suite aux nouveaux événements comportementaux personnalisés. Pour les événements personnalisés hérités, veuillez consulter la documentation héritée.

Outre le suivi des vues de page, le code de suivi HubSpot vous permet d'identifier les visiteurs, de suivre des événements et de suivre manuellement les vues de page sans recharger la page. L'API du code de suivi vous permet de créer de manière dynamique des événements et de suivre des données d'événement dans HubSpot.

Si votre site utilise la bannière de consentement de confidentialité, découvrez comment gérer les cookies qui sont ajoutés au navigateur d'un visiteur avec l'API de la bannière de cookies.

Les appels de fonction sont déclenchés dans le tableau _hsq. Par exemple :

var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', { path string }])

Dans cet article, découvrez comment ajouter des fonctions au code de suivi pour identifier les visiteurs, suivre les vues de page, envoyer des données d'événement et bien plus encore.

Identification des contacts

L'outil Analytics de HubSpot identifie les contacts à l'aide de deux types de données :

  • le usertoken, qui est stocké dans le cookie de navigateur hubspotutk du visiteur ;
  • l'adresse e-mail du contact.

Lorsque le code de suivi HubSpot suit l'action d'un visiteur, comme une vue de page, il associe automatiquement cette action avec le usertoken. Lorsque vous utilisez l'API du code de suivi pour identifier un visiteur avec l'adresse e-mail, le système d'analytics associera cette adresse e-mail au usertoken, permettant à HubSpot de mettre à jour une fiche d'informations de contact existante ou de créer une nouvelle fiche d'informations. Les données analytiques associées au usertoken, telles que les vues de page et la source d'origine, apparaîtront alors sur la fiche d'informations de contact.

Si vous connaissez l'identité d'un visiteur (par exemple, l'adresse e-mail), vous pouvez utiliser la fonction d'identification pour définir des identités dans le traceur. Vous pouvez ensuite envoyer l'identité à HubSpot en faisant un appel trackPageView ou trackCustomBehavioralEvent distinct.

Lors de l'utilisation de cette fonction, gardez à l'esprit ce qui suit :

  • Évitez d'utiliser un champ d'e-mail pour les visiteurs inconnus, car HubSpot créera une fiche d'informations de contact avec cet e-mail et le cookie usertoken du visiteur sera associé à cette fiche d'informations. Ainsi, tous les visiteurs inconnus seront associés à ce contact unique.
  • Si vous définissez une identité sur une fiche d'informations de contact et que vous avez des propriétés uniques, nous supprimerons toutes les propriétés de l'identité contraires à cette spécificité.

Identifier un visiteur

Remarque : Si votre compte a été créé avant le 8 septembre 2021 et configuré pour permettre la mise à jour des propriétés de contact via le code de suivi, vous pouvez également inclure d'autres propriétés de contact à mettre à jour avec cette fonction. Cette fonctionnalité est rendue obsolète pour les comptes créés après le 8 septembre 2021.

_hsq.push(["identify", { {identity details} }]);

Utilisez ce point de terminaison pour identifier les visiteurs et les contacts du site web.

  • Visiteur : désigne tout visiteur du site web, qu'il s'agisse d'un contact HubSpot ou non. HubSpot ne crée pas de fiches d'informations pour les visiteurs comme il le fait pour les contacts.
  • Contact : désigne un visiteur ou un contact hors ligne qui a une fiche d'informations dans HubSpot. Un contact peut être identifié par son adresse e-mail unique.

Pour identifier manuellement un visiteur ou un contact, vous pouvez utiliser une adresse e-mail ou un identifiant externe unique :

  • Adresse e-mail : identifiez un visiteur par son adresse e-mail lorsque vous souhaitez mettre à jour un contact existant ou en créer un. Si un contact avec cette adresse e-mail existe dans HubSpot, sa fiche d'informations de contact sera mise à jour avec les données analytiques. Si aucun contact n'existe à cette adresse e-mail, une nouvelle fiche d'informations sera créée.
  • ID : un identifiant externe personnalisé qui identifie le visiteur. L'identification d'un visiteur avec cet ID associera les données analytiques à ce visiteur. Cependant, l'utilisation de l'ID seul ne créera pas de contact dans HubSpot. Les données analytiques peuvent être associées à un contact existant via cette méthode uniquement si :
    • le visiteur a déjà été identifié à la fois par son ID et par son adresse e-mail ;
    • le visiteur a déjà été identifié par son ID et a également une soumission de formulaire associée à sa fiche d'informations.

Remarque : Cet ID externe peut être utilisé avec le code de suivi HubSpot uniquement. Cet ID ne peut pas être utilisé pour récupérer ou mettre à jour des fiches d'informations via d'autres outils ou API de HubSpot. Si vous connaissez l'adresse e-mail du visiteur, il est recommandé de l'utiliser comme identifiant unique. De même, vous ne devez identifier un visiteur par son ID uniquement si vous ne connaissez pas son adresse e-mail.

Si vous avez précédemment envoyé des données analytiques à HubSpot uniquement à l'aide de l'ID du visiteur, vous pouvez ultérieurement inclure l'ID et une adresse e-mail pour associer les données de cet ID à un contact. Le contact existant sera alors mis à jour ou créé si aucun contact n'existe actuellement.

/* The below example gets the value of a query string parameter '?email=' and uses that to identify the visitor */ function getParameterByName(name) { var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search); return match && decodeURIComponent(match[1].replace(/\+/g, ' ')); } var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email") }]); /* The below example sets the email, as well as a custom property favorite_color */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email"), favorite_color: 'orange' }]); /* The below example sets the email and a custom external ID for the visitor. This assumes that your site includes a variable named 'user' that includes that user's ID in an 'id' property, and their email in an 'email' property. */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: user.email, id: user.id }]);
Lors de l'utilisation de cette fonction, gardez à l'esprit ce qui suit :
  • Cette fonction stocke les données dans le traqueur (tracker), mais celles-ci ne sont pas transmises à HubSpot avec cet appel. Les données ne seront transmises que lors du suivi d'une vue de page ou d'un événement (avec les fonctions trackPageView ou trackEvent).
  • Un contact ne peut avoir qu'un seul ID et/ou une seule adresse e-mail. Si vous essayez d'attribuer deux ID à une adresse e-mail, seul le premier ID sera associé à l'adresse e-mail.
  • Vous devez inclure une adresse e-mail pour lier les données à un contact.
  • Si votre compte a été créé avant le 8 septembre 2021 et configuré pour permettre la mise à jour des propriétés de contact via le code de suivi, vous pouvez également inclure d'autres propriétés de contact à mettre à jour avec cette fonction.
  • Cette fonction ne restaurera pas les contacts précédemment supprimés. Ces contacts doivent être restaurés dans HubSpot.

Suivi dans des applications d'une seule page

Le code de suivi HubSpot enregistre automatiquement une vue de page lorsque le code est chargé pour la première fois, mais vous pouvez également suivre manuellement les vues de page dans une application d'une seule page sans recharger le code de suivi. Vous pouvez utiliser les fonctions setPath et trackPageView pour mettre à jour et suivre la page actuelle. Par exemple :

<!-- Set up the path for the initial page view --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/home']); </script> <!-- Load the HubSpot tracking code --> <!-- Start of HubSpot Embed Code --> <script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/{hubId}.js"> </script> <!-- End of HubSpot Embed Code --> <!-- Tracking subsequent page views --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/about-us']); _hsq.push(['trackPageView']); </script>

Définir le chemin de la page

hsq.push(['setPath', { path string }])

Mettez à jour le chemin de la page actuelle stocké dans le suivi. Cette fonction doit être utilisée par des applications d'une seule page pour mettre à jour la page actuelle lorsqu'une page est chargée. Après avoir utilisé cette fonction pour mettre à jour le chemin, vous devrez appeler la fonction trackPageView pour suivre la vue de la page actuelle.

Les applications d'une seule page doivent passer un appel setPath dans _hsq avant le chargement du code de suivi pour définir l'URL suivie pour la première vue. Consultez la section Suivre une vue de page ci-dessous pour obtenir un exemple.

Lorsque vous appelez setPath, vous inclurez le chemin de la page actuelle. Le chemin défini sera traité par rapport au domaine actuel consulté. Le chemin doit toujours commencer par une barre oblique. Si votre URL contient également des paramètres, ces derniers devront être inclus dans le chemin. Consultez le code ci-dessus pour des exemples.

Lors de l'utilisation de cette fonction, gardez à l'esprit ce qui suit :
  • Tout chemin défini à l'aide de la fonction setPath remplacera les données dans l'en-tête de référent. Si vous appelez setPath une fois, vous devrez utiliser setPath pour mettre à jour le chemin pour chaque vue que vous souhaitez suivre.
  • L'appel répété de setPath remplacera le référent, ce qui peut avoir un impact sur la source d'origine d'un contact, selon le moment où une demande de suivi est effectuée. 
  • Cette fonction ne peut mettre à jour que le chemin de l'URL. Le domaine est défini automatiquement en fonction de l'URL de la page en chargement et le chemin défini à l'aide de cette fonction est toujours considéré par rapport à ce domaine détecté.
Example usage: // These examples assume that the domain of the site is // www.mydomain.com // Set the path to '/' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/ // Set the path to '/contact-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/contact-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/contact-us // Set the path to '/blog/post?utm_campaign=my-campaign' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/blog/post?utm_campaign=my-campaign']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/blog/post?utm_campaign=my-campaign // Set the path to '/#/about-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/about-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/#/about-us

Suivre une vue de page

_hsq.push(['trackPageView']);

Suivez la vue de la page actuelle. Cette fonction est automatiquement appelée lorsque le code de suivi est chargé sur une page, mais vous pouvez appeler manuellement cette fonction pour suivre les vues suivantes dans une application d'une seule page.

Remarque : L'appel manuel de cette fonction avant ou pendant le chargement initial de la page pourrait entraîner un suivi de vues en double.

Cette fonction ne prend pas en charge des arguments. Le titre de page suivi sera la valeur actuelle de document.title.

L'URL qui est suivie est basée sur l'un des éléments suivants :

  • Le chemin défini à l'aide de la fonction setPath. Si votre site est conçu comme une application d'une seule page, cette fonction est la méthode préférée pour définir le chemin suivi. Consultez la section setPath ci-dessus pour consulter des avertissements sur la fonction.
  • Si la fonction setPath n'a jamais été appelée, l'URL suivie sera l'en-tête HTTP du référent de la demande effectuée par le navigateur du visiteur aux serveurs de suivi HubSpot (la modification de l'état de l'historique du navigateur mettra à jour la valeur utilisée pour l'en-tête). L'utilisation de l'en-tête du référent ne prend pas en charge les fragments d'URL (tout élément après # dans l'URL), car ceux-ci ne sont pas inclus dans l'en-tête du référent.
Example usage: // Track a new page using setPath: // Update the path stored in the tracker: var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/new-page']); // Track the page view for the new page _hsq.push(['trackPageView']); // Track a new page by updating the browser state: // Update the browser state, showing "updated.html" in the browser address bar var stateObj = { foo: 'updated' }; history.pushState(stateObj, "updated page", "updated.html"); //Track the page view for the new page, '/updated.html' var _hsq = window._hsq = window._hsq || []; _hsq.push(['trackPageView']);

Lorsque vous utilisez cette fonction, tenez compte des informations suivantes :

  • S'il n'est pas possible d'empêcher l'appel automatique de cette fonction lors du chargement du code de suivi, vous pouvez contrôler l'URL enregistrée pour la page en lançant un appel setPath dans _hsq avant le chargement du code de suivi.
  • Nous déconseillons d'inclure une balise <link rel="canonical"> dans votre page si votre site est une application d'une seule page. Si votre page utilise des balises <link rel="canonical">, vous devez utiliser la fonction setPath pour mettre à jour le chemin de vos nouvelles pages, car l'URL canonique définie dans la balise de lien remplacera toute URL détectée si vous ne mettez à jour que l'état de l'historique du navigateur.

Politique de confidentialité dans le suivi

Si votre site dispose d'une bannière de consentement de confidentialité, vous pouvez utiliser des fonctions pour consulter et gérer les cookies placés dans le navigateur du visiteur. Découvrez-en davantage sur la gestion des cookies de la bannière de consentement de confidentialité.

Obtenir des paramètres de liaison inter-domaine automatique

_hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) {}]) 

Le code de suivi HubSpot peut être utilisé sur plusieurs sites avec des domaines distincts. Cette fonction vous permet d'obtenir les paramètres de requête nécessaires pour créer des liens qui vous permettront de suivre vos visiteurs sur ces domaines distincts. Ces paramètres de requête sont utilisés par le code de suivi HubSpot afin d'identifier un visiteur sur plusieurs domaines en veillant à ce que les cookies distincts des domaines distincts soient fusionnés en un seul visiteur suivi. Vous pouvez également utiliser les paramètres de requête inter-domaine dans les liens qui sont ajoutés dynamiquement à la page après le chargement du code de suivi.

Les liens inter-domaines sont uniquement nécessaires lors de la connexion d'un domaine distinct (comme domaine-un.com et domaine-deux.com) qui est également suivi pour un seul compte HubSpot. Vous n'avez pas besoin de paramètres de lien inter-domaine lors du suivi des visites entre des sous-domaines (comme www.domaine-un.com et blog.domaine-un.com). 

// Get the cross-domain query parameters and store them in a string, //so that they can be appended to links as needed. _hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) { // Add these query parameters to any links that point to a separate tracked domain crossDomainTrackingParams = '&__hstc=' + hstc + '&__hssc=' + hssc + '&__hsfp=' + hsfp; }]);

Réappliquer les gestionnaires d'événements analytiques

_hsq.push(['refreshPageHandlers'])

Cette fonction réapplique les gestionnaires d'événements analytiques configurés dans les paramètres analytiques du compte HubSpot.

Cela inclura les événements d'élément cliqué qui ont été configurés.

 Vous pouvez utiliser cette fonction pour réappliquer automatiquement les gestionnaires de clic lorsque le contenu sur la page est mis à jour, comme la mise à jour d'une section de contenu ou l'affichage d'une fenêtre modale sur la page.

Remarque : Cette fonctionnalité est automatiquement déclenchée dans le cadre de la fonction setPath. Par conséquent, vous n'aurez besoin de cette fonction que lors de la mise à jour du contenu, sans mise à jour de l'URL de la page suivie.

// Reapply event handlers after updating the page content _hsq.push(['refreshPageHandlers']);

Suivre les événements comportementaux personnalisés (Marketing Hub Entreprise uniquement)

À l'aide d'événements comportementaux personnalisés, vous pouvez lier les finalisations d'événements aux fiches d'informations de contact et remplir les propriétés d'événement avec des métadonnées sur l'événement. Pour récupérer des événements comportementaux personnalisés, utilisez l'API d'analyse web.

Grâce à l'API, les événements peuvent être déclenchés en utilisant le nom interne de l'événement, qui est attribué automatiquement lorsque vous créez l'événement. Vous pouvez trouver le nom interne d'un événement dans HubSpot ou via l'API d'événements. Découvrez comment trouver le nom interne d'un événement. 

custom-event-internal-name

Il existe trois types d'événements que vous pouvez créer dans HubSpot :

  • Événements d'élément cliqué : événements liés à des éléments cliqués sur une page web. Un ensemble de propriétés d'événement HubSpot par défaut sera automatiquement renseigné via le code de suivi. Vous pouvez personnaliser davantage ces événements avec la fonction trackCustomBehavioralEvent.
  • Événements d'URL visitée : événements liés aux chargements de page aux URL spécifiées. Un ensemble de propriétés d'événement HubSpot par défaut sera automatiquement renseigné via le code de suivi. Vous pouvez personnaliser davantage ces événements avec la fonction trackCustomBehavioralEvent.
  • Événements comportementaux suivis manuellement : les événements personnalisés propres à votre entreprise ainsi que les événements qui peuvent ne pas être automatiquement capturés par HubSpot ou par une intégration. Envoyez manuellement des données aux événements HubSpot via l'API HTTP.

Pour chaque type d'événement, HubSpot inclut un ensemble de propriétés standard qui peuvent capturer certaines métadonnées au moment de la finalisation, y compris les paramètres UTM ou des métadonnées relatives au périphérique et au système d'exploitation.

 Étant donné que cette fonction fonctionne avec le suivi des analytics de HubSpot, tous les événements déclenchés par l'API JavaScript seront automatiquement associés au cookie hubspotutk du visiteur. Ainsi, l'événement sera automatiquement lié au contact associé à ce usertoken.

trackCustomBehavioralEvent

_hsq.push(["trackCustomBehavioralEvent", { {event details} }]);

Utilisez cette fonction pour suivre un événement utilisant JavaScript et le code de suivi de HubSpot. Vous pouvez utiliser des événements pour suivre des activités spécifiques effectuées par les visiteurs sur votre site. Les événements suivis peuvent apparaître dans la chronologie des contacts.

/* Example code to fire a custom behavioral event using the name "clicked Buy Now button" when a visitor clicks an element with the 'buyNow' id. */ document.getElementById("buyNow").onclick = function() {_hsq.push(["trackCustomBehavioralEvent", { name: "pe123456_course_registration", properties: { course_id: "Math101" } }]);
Use this table to describe parameters / fields
ArgumentsFonctionnementDescription
Name
name:"internal_name"

L'ID ou le nom interne de l'événement que vous avez créé dans HubSpot.

Properties
property_name: "property_value"

Une liste de paires (clé, valeur), avec une paire par propriété.

property_name est le nom interne de la propriété d'événement que vous avez créée pour l'événement et property_value est la valeur à ajouter à la propriété. 

Vous pouvez également suivre les propriétés non définies et revenir en arrière pour les créer après le suivi des événements.

Personnaliser votre code de suivi pour envoyer des données d'événement comportemental personnalisé

Par défaut, HubSpot crée un ensemble de propriétés pour chaque événement que vous créez. Pour les événements d'élément cliqué ou d'URL visitée, HubSpot remplira automatiquement certaines de ces propriétés avec des données. Mais vous pouvez également personnaliser votre code de suivi pour envoyer des données aux propriétés de l'événement.

  • Dans votre compte HubSpot, accédez à Reporting > Outils d'analytics.
  • Cliquez sur Événements comportementaux personnalisés.
  • Cliquez sur le nom de l'événement que vous souhaitez suivre.
  • Dans Propriétés, copiez le nom interne de l'événement.custom-clicked-element-event-internal-name0
  • Ensuite, dans le tableau des propriétés, cliquez sur le nom de la propriété d'événement vers laquelle vous souhaitez envoyer des données.
  • Dans le panneau de droite, cliquez sur l'icône Source </> pour afficher le nom interne de la propriété. Vous utiliserez ce nom lors de la personnalisation du code de suivi.
    custom-behavioral-event-property-internal-name0
  • Maintenant que vous disposez de vos données d'événement et de propriété d'événement, cliquez sur l'icône Paramètres pour accéder aux paramètres de votre compte. Puis, dans le menu latéral de gauche, accédez à Suivi et analytics > Code de suivi.
  • Cliquez sur Personnaliser JavaScript.
    tracking-code-customize-javascript0
  • Dans l'angle supérieur droit, cliquez sur Ajouter un Javascript personnalisé.
  • Dans la barre latérale de droite, saisissez un nom pour votre JavaScript personnalisé, puis saisissez le JavaScript, y compris la fonction trackCustomBehavioralEvent. Ce code JavaScript doit être exécuté après le chargement du code de suivi d'une page.
// example usage _hsq.push(['trackCustomBehavioralEvent',{ name: '((behavioral_event_internal_name))”, properties: { internal_property_name: property_value} } ]);

Par exemple, si votre événement suit une inscription à un cours lorsqu'un bouton avec l'ID de HTML register_for_econ101 est cliqué, votre JavaScript peut ressembler à ce qui suit : customize-tracking-code0-1

  • Cliquez sur Enregistrer pour enregistrer votre JavaScript. Votre code de suivi va maintenant se charger avec votre JavaScript personnalisé.
Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.