Suivi des gadgets

Ce document décrit comment utiliser la nouvelle API Gadget pour le suivi des gadgets Google Analytics. Cette API offre un modèle de données amélioré et un suivi des performances permettant de collecter des statistiques dans les rapports Analytics pour vos gadgets.

  1. Avant de commencer
  2. Suivi de votre gadget
  3. Méthodes de suivi
  4. Considérations liées à l'utilisation
  5. Conseils
 

Avant de commencer

Dans Google Analytics, chaque domaine ou sous-domaine de site Web unique que vous ajoutez à votre compte est suivi dans une vue distincte (profil) et reçoit un ID de domaine distinct. Étant donné que chaque gadget fonctionne sur son propre sous-domaine sur le site hôte gmodules.com, il est préférable de suivre chaque gadget que vous créez dans sa propre vue (profil) et avec un identifiant de domaine unique.

Pour ce faire, le moyen le plus simple consiste à laisser Google Analytics générer un identifiant unique pour vous.

  1. Pour commencer, connectez-vous à Google Analytics ou créez un compte Google Analytics.
    • Les nouveaux utilisateurs doivent voir la page Créer un compte.
    • Les utilisateurs existants doivent accéder à la page Paramètres Analytics, puis cliquer sur Ajouter une vue de site Web (profil). (Veillez à choisir nouveau domaine.)
  2. Sur l'une de ces pages, saisissez une URL de site Web valide.
    3. L'URL du site Web étant une simple chaîne que le logiciel Google Analytics associe à votre ID de domaine, cette URL peut correspondre à n'importe quelle chaîne d'URL de site Web valide, qu'elle soit fabriquée ou réelle. Vous n'allez pas du tout installer le code de suivi sur des pages Web et n'aurez pas besoin d'accéder à des pages du site Web.
  3. Cliquez sur le bouton pour passer à l'écran suivant.
    4. Lorsque l'extrait de code de suivi apparaît, copiez l'ID de domaine unique dans un bloc-notes. L'extrait de code généré automatiquement contient cet ID de domaine au format UA-123456-1.
  4. Cliquez sur le bouton Finish (Terminer).
    5. Le nom de l'URL de votre site Web doit s'afficher dans la liste des vues (profils). Vous pouvez également modifier le nom de la vue (profil) pour lui attribuer un nom plus explicite. Pour ce faire, cliquez sur le lien Modifier correspondant, puis cliquez à nouveau sur Modifier.
  5. Utilisez l'identifiant de domaine généré dans le code de suivi de votre gadget.
    6. Les ID de domaine Analytics se présentent comme suit:
    UA-123456-1
 

Suivi de votre gadget

Le processus de suivi de votre gadget implique trois ajouts au code de votre gadget:

  1. Activation de la fonctionnalité...
  2. Création d'un objet de suivi
  3. Suivi de votre gadget à l'aide de l'une des deux méthodes suivantes.

L'exemple de code de gadget suivant illustre chacun de ces ajouts de code, qui sont expliqués ci-dessous. Vous pouvez utiliser ce fichier exemple pour créer votre propre gadget.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Analytics Test">
     <!-- Sets the feature -->
     <Require feature="com.google.gadgets.analytics" /> 
     <Require feature="setprefs" /> 
  </ModulePrefs>
  <UserPref 
      name="counter"
      datatype="hidden"
      default_value="0" />
  <Content type="html"> 
  <![CDATA[ 
      <script>
      // Track this gadget using Google Analytics.

      // Creates a tracking object and uses reportPageview method to call gadget view
      var ga = new _IG_GA("UA-00000-1");
      ga.reportPageview('/view/counterGadget');

      // Suppose, for example, you have a gadget with two counter buttons.
      // You can track interactions with those counters via Analytics.

      // Increment value of "counter" user preference
      function incrementCounter() {
         var count = prefs.getInt("counter");

         prefs.set("counter", count + 1);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Increment", "Button", 0);
      }

      // Reset value of "counter" userpref to 0
      function resetCounter(){
         prefs.set("counter", 0);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Reset", "Button", 0);
      }
      </script>
      <form name="counter">
      <input type=button value="Reset" name="reset" onClick="resetCounter()">
      <input type=button value="Count" name="count" onClick="incrementCounter()">
      </form>
  ]]>
  </Content>
</Module>

1. Activation de la fonctionnalité...

Commencez par activer la fonctionnalité en important la bibliothèque Analytics à l'aide de l'espace de noms de la fonctionnalité:

 <Require feature="com.google.gadgets.analytics" />

2. Créer un objet de suivi

L'API de suivi Analytics respecte le même modèle orienté objet que le code de suivi ga.js. Par conséquent, avant d'effectuer le suivi de votre gadget, instanciez un objet de suivi:

var ga = new _IG_GA("UA-123456-1");

C'est ici que vous insérerez l'ID de domaine généré en suivant les étapes ci-dessus.

Vous devez utiliser l'ID de domaine complet avec le chiffre de fin unique. Sinon, l'appel de l'objet de suivi échouera.

3. Suivi de votre gadget

L'API Gadget propose deux méthodes que vous pouvez utiliser pour suivre l'interaction sur vos gadgets:

  • La méthode des URL virtuelles
    • ga.reportPageview(path);

    Cette méthode effectue le suivi des statistiques des gadgets en tant que pages vues spéciales. Elle est identique à celle utilisée dans la version précédente de l'API du gadget Google Analytics. Cette méthode vous permet de mettre à jour n'importe quel code de suivi de gadget existant, sans aucune incidence sur la présentation de vos rapports Google Analytics existants. L'affichage des données de rapport sur vos gadgets est le même que pour les pages Web.

    Lorsque vous utilisez la méthode de l'URL virtuelle pour suivre l'interaction avec le gadget, chaque appel est enregistré en tant que demande de page pour la chaîne que vous fournissez en tant que paramètre de la méthode. Vous pouvez profiter de ce comportement pour transmettre un chemin d'URL fictif afin d'afficher des rapports sur les gadgets dans l'interface Google Analytics, comme vous le feriez pour des rapports sur les pages de votre site Web. Par exemple, vous pouvez utiliser des chemins distincts pour suivre à la fois les vues et les interactions avec les gadgets: 

    ga.reportPageview('/view/counterGadget');
ga.reportPageview('/click/increment');
ga.reportPageview('/click/reset');

  • La méthode de suivi des événements
    • ga.reportEvent(name, action, [[]label], [[]value]);

    Cette méthode n'est disponible que dans la nouvelle API du gadget Analytics. Cette méthode vous permet d'effectuer le suivi des pages vues (affichage du gadget, par exemple) indépendamment des interactions des utilisateurs avec votre gadget.

    Remarque: Pour le moment, le suivi des événements est disponible en version bêta fermée. Utilisez la méthode de l'URL virtuelle si vous n'avez pas accès au suivi des événements.

    La méthode "event" fournit un modèle différent que vous pouvez utiliser avec le suivi des gadgets. Tout d'abord, les appels d'événements sont calculés séparément des appels de page vue, et les données qui en résultent sont affichées dans une partie distincte des rapports "Contenu" de Google Analytics. Vous pouvez ainsi effectuer le suivi de l'affichage d'un gadget séparément des interactions des utilisateurs sur celui-ci, sans que celles-ci n'augmentent le nombre global de vues du gadget. Deuxièmement, cette méthode utilise le modèle de suivi des événements, dont la structure est spécialement conçue pour analyser les interactions des utilisateurs sur les gadgets. Dans ce modèle, l'étiquette et la valeur sont des paramètres facultatifs.

    Pour reprendre l'exemple des compteurs, nous pouvons utiliser la méthode "event" pour suivre les fonctions de gadget déclenchées. Nous pouvons transmettre le type de commande, qui est un bouton dans les deux cas. 

    ga.reportEvent("Counter Gadget", "Increment", "Button");
ga.reportEvent("Counter Gadget", "Reset", "Button");

    Il s'agit d'un exemple très simple, mais le modèle de suivi des événements est une structure extrêmement flexible que vous pouvez affiner afin de répondre aux exigences spécifiques du suivi de votre gadget. Pour en savoir plus, consultez la documentation sur les événements de suivi.

 

Méthodes de suivi

Actuellement, la fonctionnalité Analytics propose les méthodes suivantes. Leur utilisation est abordée ci-dessus.

  • reportPageview()
    • Nécessite une chaîne pour renseigner correctement les rapports sur le contenu. Généralement, cette chaîne prend la forme d'un chemin que vous définissez à des fins de création de rapports. La valeur transmise via cette méthode est envoyée dans la requête GIF via la variable utmp. Utilisez cette méthode pour suivre le chargement des gadgets et les interactions avec ces derniers. 
    ga.reportPageview("/view/gadgetName");
    parameters
    String  path Chemin d'accès à fournir à l'URL virtuelle de cet élément.

  • reportEvent()
    • Nécessite le nom du gadget et le paramètre d'action afin d'insérer correctement les données suivies dans les rapports de suivi des événements. Les autres paramètres sont facultatifs. Les valeurs transmises via cette méthode sont envoyées dans la vue de la requête GIF dans la variableU utme.

    parameters
    String  name  Obligatoire.Chaîne utilisée au premier niveau des rapports sur le suivi des événements. Par exemple, si vous effectuez le suivi des interactions sur plusieurs éléments du gadget, vous utiliserez probablement le nom du gadget lui-même pour ce paramètre, de sorte que tous les suivis des interactions du gadget soient regroupés dans une même section des rapports Google Analytics.

    String  action  Obligatoire. Chaîne permettant de segmenter davantage l'interaction avec le gadget dans les rapports de suivi des événements. Pour en savoir plus, consultez la documentation sur les événements de suivi.

    String  label  Facultatif. Chaîne que vous pouvez utiliser comme segment secondaire pour votre gadget.

    Int  value  Facultatif. Numéro que vous pouvez fournir en tant que valeur pour l'interaction avec le gadget. Ce nombre est agrégé pour chaque appel de la méthode.

 

Remarques sur l'utilisation

L'API du gadget Google Analytics implique un certain nombre de considérations d'utilisation:

  • Conteneurs compatibles
    • L'API des gadgets Google Analytics prend en charge de nombreux types de conteneurs, y compris, mais sans s'y limiter :
    • iGoogle
    • Ouvrir la syndication
    • OpenSocial
    • Gadgets
  • Types de gadgets non compatibles
    • L'API des gadgets Google Analytics n'est pas compatible avec les types de gadgets suivants :
    • Gadgets intégrés (type=html-inline)
    • Mapplets
    • Gadgets de type d'URL (type-url)
    • Gadget Ads sur Google AdSense
  • Remarques concernant le domaine
    • Lorsque vous avez besoin de la fonctionnalité Google Analytics pour votre gadget, celui-ci redirige les utilisateurs vers <subdomain>.gmodules.com, où <subdomain> est un sous-domaine unique et aléatoire. Par conséquent, tout le contenu du gadget s'affiche dans ce sous-domaine. Exemple : 3nvma227-a.gmodules.com. De plus, tous les cookies de suivi Google Analytics sont définis sur ce sous-domaine unique. Pour cette raison, les mapplets ne sont pas compatibles avec la fonctionnalité de suivi Analytics. Vous devez spécifiquement autoriser le contenu Flash à accéder à cette fonctionnalité de suivi (voir ci-dessous).
  • Gadgets avec du contenu Flash
    • Les gadgets utilisant du contenu Flash doivent spécifiquement permettre la communication entre l'URL Flash et l'URL du gadget, en définissant le paramètre allowScriptAccess sur "Toujours". 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

Conseils

Comment utiliser au mieux la méthode des URL virtuelles

Si vous n'avez pas accès à la méthode de suivi des événements pour vos gadgets, suivez ces recommandations pour suivre vos gadgets avec la méthode d'URL virtuelle:

  • Segmentez distinctement le chargement de votre gadget.
    • Vous pouvez appeler ga.reportPageview() lors du chargement du gadget en fournissant un chemin qui segmente les statistiques de chargement/d'affichage du gadget séparément des statistiques d'interaction des gadgets. Les données de rapport sur le contenu du gadget seront ainsi conservées dans un "répertoire" distinct de celui des interactions sur le gadget, de sorte que vous puissiez voir vos vues globales séparément du nombre d'interactions sur le gadget lui-même. Par exemple, vous pouvez utiliser l'extrait de code suivant dans votre gadget pour afficher toutes les statistiques relatives au chargement de celui-ci : 
      ga.reportPageview('/view/gadgetName');
  • et segmenter les différents types d'interaction.
    • Appelez ga.reportPageview() avec un chemin qui segmente différentes interactions utilisateur. De cette manière, vous pouvez obtenir des rapports distincts sur le contenu des liens de gadgets, des boutons de gadget ou d'autres widgets dont vous souhaitez peut-être effectuer le suivi pour les données d'interaction. Exemple :
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

Utiliser la méthode de suivi des événements

Si vous avez accès à la fonctionnalité de suivi des événements dans les rapports Google Analytics, vous pouvez tirer parti du modèle de données extrêmement flexible pour tirer le meilleur parti du suivi de vos objets. Voici quelques conseils :

  • Effectuez le suivi de l'affichage ou des impressions du gadget à l'aide de ga.reportPageview(), et effectuez le suivi des interactions du gadget à l'aide de ga.reportEvent().
    • Les vues de gadgets s'afficheront dans la section "Contenu" pour les données de la page, tandis que les interactions avec les gadgets s'afficheront dans la section "Événements", sous les rapports "Contenu".
  • Utilisez document.referrer comme paramètre pour savoir où votre gadget a été placé.
    • Dans le gadget, document.referrer correspond généralement à l'URL de la page du conteneur. Vous pouvez donc la transmettre en tant que paramètre de libellé dans la méthode ga.reportEvent():
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Dépannage

Vous pouvez utiliser des outils tiers pour analyser la chaîne de demande GIF de votre gadget afin de vérifier que les données sont envoyées aux rapports Google Analytics comme vous le souhaitez. Une fois que le gadget est correctement hébergé et que vous travaillez sur votre page de test, analysez la chaîne de demande GIF comme suit:

  • Méthode "Page vue"
    • Recherchez la variable utmp dans les paramètres de demande GIF. Les informations associées à cette variable seront envoyées aux rapports Google Analytics en tant que "chemin d'accès" pour le gadget.
  • Méthode de suivi des événements
    • Recherchez la variable UTM dans les paramètres de demande GIF. Ces informations doivent se présenter au format 5(object*action*label)(value).

Pour en savoir plus sur la résolution des problèmes liés au code de suivi, consultez le Guide de dépannage GATC.