Introduction à ga.js (ancienne version)

ga.js est une bibliothèque JavaScript permettant de mesurer la manière dont les utilisateurs interagissent avec votre site Web. Il s'agit d'une ancienne bibliothèque. Si vous faites vos premiers pas avec Google Analytics, nous vous conseillons d'utiliser la dernière bibliothèque de suivi : analytics.js.

Guide de démarrage rapide pour le code de suivi

L'extrait Analytics est un petit extrait de code JavaScript que vous collez dans vos pages. Il active le suivi Google Analytics en insérant ga.js dans la page. Pour l'utiliser sur vos pages, copiez l'extrait de code ci-dessous, en remplaçant UA-XXXXX-X par l'ID de votre propriété Web. Collez cet extrait dans le modèle de page de votre site Web afin qu'il apparaisse avant la balise de fermeture </head>.

Si vous avez besoin d'effectuer d'autres opérations que le suivi de page de base, consultez la documentation de référence sur le suivi pour obtenir la liste des méthodes disponibles dans l'API, ainsi que le guide d'utilisation pour en savoir plus sur la syntaxe asynchrone. Pour obtenir des instructions détaillées sur la configuration du suivi, consultez l'article du centre d'aide sur la configuration du suivi.

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

L'extrait de code ci-dessus représente la configuration minimale requise pour effectuer le suivi d'une page de manière asynchrone. Elle utilise _setAccount pour définir l'ID de propriété Web de la page, puis appelle _trackPageview pour renvoyer les données de suivi aux serveurs Google Analytics.

Important:Si vous mettez à jour vos pages de l'extrait traditionnel vers la dernière version asynchrone, vous devez d'abord supprimer l'extrait de suivi existant. Nous vous déconseillons d'utiliser les deux extraits ensemble sur la même page. Pour obtenir des instructions sur la migration, consultez la page Migrer vers Async.

Fonctionnement de la syntaxe asynchrone

L'objet _gaq rend la syntaxe asynchrone possible. Il agit comme une file d'attente, c'est-à-dire une structure de données de type premier arrivé, premier sorti, qui collecte les appels d'API jusqu'à ce que ga.js soit prêt à les exécuter. Pour ajouter un élément à la file d'attente, utilisez la méthode _gaq.push.

Pour envoyer un appel d'API dans la file d'attente, vous devez le convertir de la syntaxe JavaScript traditionnelle en un tableau de commandes. Les tableaux de commandes sont simplement des tableaux JavaScript conformes à un certain format. Le premier élément d'un tableau de commandes est le nom de la méthode d'objet de suivi que vous souhaitez appeler. Il doit s'agir d'une chaîne. Les autres éléments sont les arguments que vous souhaitez transmettre à la méthode de l'objet de suivi. Il peut s'agir de n'importe quelle valeur JavaScript.

Le code suivant appelle _trackPageview() à l'aide de la syntaxe traditionnelle:

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

Le code équivalent dans la syntaxe asynchrone nécessite deux appels à _gaq.push.

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

Avec la syntaxe asynchrone, la création de l'objet de suivi est implicite, mais nous avons encore besoin d'un moyen de définir l'ID de propriété Web de l'outil de suivi. La méthode _setAccount a été ajoutée pour fournir cette fonctionnalité. Toutes les autres méthodes d'objet de suivi sont les mêmes pour le suivi asynchrone et le suivi traditionnel. Seule la syntaxe est différente.

Pour en savoir plus sur la syntaxe asynchrone, consultez les documents de référence de suivi concernant la méthode _gaq.push.

Haut de page

Suivi avec les gestionnaires d'événements HTML

La syntaxe de suivi asynchrone doit également être utilisée à partir des gestionnaires d'événements DOM. Par exemple, le bouton suivant génère un événement lorsqu'un utilisateur clique dessus.

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

Même si vous cliquez sur ce bouton avant que le navigateur ait fini de charger ga.js, l'événement sera capturé et exécuté à terme. En utilisant le suivi traditionnel, le navigateur peut générer une exception dans ce cas.

Haut de page

Transférer des fonctions dans la file d'attente

En plus des tableaux de commandes, vous pouvez également transférer des objets fonction dans la file d'attente _gaq. Les fonctions peuvent contenir n'importe quel code JavaScript arbitraire et, comme les tableaux de commandes, sont exécutées dans l'ordre dans lequel elles sont transmises à _gaq. Cette technique est utile pour appeler les API de suivi qui renvoient des valeurs. Par exemple, le code suivant crée une URL d'association et définit la propriété href pour un lien avec le résultat.

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

L'exemple ci-dessus utilise _gat pour créer un objet de suivi, mais comme il est attribué à une variable locale, le code situé en dehors de la fonction ne peut pas l'utiliser. Bien que cela soit acceptable, vous pouvez utiliser la méthode _gat._createTracker pour créer un objet permanent accessible dans le monde entier. Le code suivant montre comment cela fonctionne.

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

L'exemple ci-dessus crée un outil de suivi asynchrone dans la fonction, puis le référence ultérieurement par son nom dans le tableau de commandes.

Le cas d'utilisation inverse est également possible. Par exemple, si vous devez utiliser un objet de suivi asynchrone créé via un tableau de commandes précédemment transmis, utilisez la méthode _gat._getTrackerByName. Le code suivant montre comment cela fonctionne.

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

Haut de page

Un seul push, plusieurs commandes

Au lieu de saisir _gaq.push(...) pour chaque appel, vous pouvez transférer toutes vos commandes en même temps. Le code suivant illustre cette technique.

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

Cela fonctionne, car la méthode _gaq.push imite la méthode Array.push, qui permet de transférer plusieurs éléments avec un seul appel.

Haut de page

Division de l'extrait

Si vous préférez placer l'extrait Analytics au bas de la page, sachez qu'il n'est pas nécessaire de le placer intégralement en bas. Vous pouvez conserver la plupart des avantages du chargement asynchrone en divisant l'extrait en deux : vous pouvez conserver la première moitié en haut de la page et déplacer le reste en bas. Étant donné que la première partie de l'extrait de code de suivi a peu ou pas d'effet sur le rendu de la page, vous pouvez la laisser en haut et placer celle qui insère ga.js au bas de l'extrait.

Voici à quoi pourrait ressembler l'extrait de code asynchrone divisé en deux:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

Les deux extraits de code doivent être encapsulés dans leurs propres tags de script, mais seules les six dernières lignes de l'extrait asynchrone d'origine doivent être déplacées vers le bas. Toutes les lignes qui transmettent des méthodes sur _gaq peuvent rester en haut.

Haut de page

Éviter les pièges courants

Lorsque vous utilisez la syntaxe asynchrone ou traditionnelle, tenez compte des points suivants:

  • Les noms de méthodes sont sensibles à la casse.
    Si vous utilisez un nom de méthode sans casse appropriée, vos appels de méthode ne fonctionneront pas. Exemples :
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • Utilisez des noms de méthodes corrects.
    Si le suivi ne fonctionne pas correctement, vérifiez que vous utilisez le nom correct pour la méthode. Exemples :
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • Seules des chaînes entre guillemets doivent être transmises. Ne laissez pas les autres types de guillemets.
    Toute valeur qui n'est pas une chaîne, telle que des valeurs booléennes, des littéraux d'objet, des fonctions ou des tableaux, doit être transmise sans guillemets. N'utilisez que des guillemets lorsque vous transmettez un élément destiné à être interprété comme une chaîne. Si vous effectuez une migration à partir de la syntaxe traditionnelle, tout paramètre de fonction transmis sans guillemets doit rester sans guillemets dans la syntaxe asynchrone. Exemples :
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • Assurez-vous que les chaînes ne contiennent pas d'espace blanc de début ou de fin.
    Exemples :
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

Haut de page

Désactivation du suivi

Dans certains cas, il peut être nécessaire de désactiver le code de suivi Google Analytics sur une page sans avoir à supprimer l'extrait de code. Par exemple, vous pouvez choisir cette option si les règles de confidentialité de votre site permettent à l'internaute de désactiver le suivi Google Analytics.

L'extrait de suivi ga.js inclut désormais une propriété de fenêtre qui, lorsqu'elle est définie sur true, empêche l'extrait de suivi d'envoyer des données à Google Analytics. Lorsque Google Analytics tente de définir un cookie ou de renvoyer des données aux serveurs Google Analytics, il vérifie si cette propriété est définie sur true. Si c'est le cas, cela aura le même effet que si le plug-in de navigateur pour la désactivation de Google Analytics était installé pour le visiteur.

Pour désactiver le suivi, définissez la propriété de fenêtre suivante sur "true" :

window['ga-disable-UA-XXXXXX-Y'] = true;

Où la valeur UA-XXXXXX-Y correspond à l'ID de propriété Web sur laquelle vous souhaitez désactiver le suivi.

Cette propriété de fenêtre doit être définie avant que le code de suivi ne soit appelé. Vous devez définir cette propriété sur chaque page sur laquelle vous souhaitez désactiver le suivi Google Analytics. Si la propriété n'est pas définie ou si elle est définie sur "false", le suivi fonctionnera normalement.

Par exemple, si votre code de suivi Google Analytics sur une page inclut:

_gaq.push['_setAccount', 'UA-123456-1']

Si vous souhaitez empêcher ce code de suivi de définir des cookies ou de renvoyer des données à Google Analytics, utilisez le code suivant avant d'appeler le code de suivi:

window['ga-disable-UA-123456-1'] = true;

Si vous utilisez plusieurs outils de suivi sur une page avec plusieurs ID de propriété Web, vous devez définir la variable window['ga-disable-UA-XXXXXX-Y'] équivalente sur true pour chaque propriété Web afin de désactiver complètement le suivi Google Analytics sur cette page.

Exemple

Voici un exemple simple de code que vous pouvez utiliser pour fournir une fonctionnalité de désactivation à vos utilisateurs.

Tout d'abord, ajoutez un nouveau lien HTML vers votre site afin d'exécuter la logique de désactivation:

<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>

Ajoutez ensuite l'extrait de code suivant avant l'extrait de code ga.js. Veillez à remplacer la valeur UA-XXXX-Y de gaProperty par la propriété utilisée sur votre site. Il s'agit de la même valeur que celle que vous transmettez à la commande _setAccount.

<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';

// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
  window[disableStr] = true;
}

// Opt-out function
function gaOptout() {
  document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
  window[disableStr] = true;
}
</script>

Lorsqu'un utilisateur clique sur le lien HTML de désactivation, la fonction gaOptout personnalisée s'exécute. Il définira un cookie pour une longue période à l'avenir et désactivera la collecte de données analytics.js. Lorsqu'un utilisateur revient sur ce site, le script ci-dessus vérifie si le cookie de désactivation a été défini. Si c'est le cas, la collecte de données analytics.js sera également désactivée.

Forcer le protocole SSL (HTTPS)

Pour forcer Google Analytics à toujours envoyer des données via SSL, même à partir de pages non sécurisées (HTTP), utilisez la méthode _gat._forceSSL, comme dans cet exemple:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

Haut de page