Gadget de seguimiento

Este documento describe cómo utilizar la nueva API de gadget para el seguimiento de gadgets de Analytics. Esta API ofrece un modelo de datos mejorado y un seguimiento del rendimiento para recopilar estadísticas de informes de Analytics para tus gadgets.

  1. Antes de comenzar
  2. Cómo realizar un seguimiento de tu gadget
  3. Métodos de seguimiento
  4. Consideraciones de uso
  5. Sugerencias
 

Antes de comenzar

En Google Analytics, el seguimiento de cada dominio de sitio web o subdominio único que agregas a tu cuenta se realiza en una vista independiente (perfil) y se le asigna un ID de dominio diferente. Dado que cada gadget funciona en su propio subdominio, en el sitio host de gmodules.com, te recomendamos que realices el seguimiento de cada gadget que crees en su propia vista (perfil) y con un ID de dominio exclusivo.

La forma más sencilla de hacerlo es dejar que Google Analytics genere un ID único por ti.

  1. Para comenzar, acceda a Google Analytics o regístrese para obtener una cuenta de Google Analytics.
    • Los usuarios nuevos deberían ver una página de registro de cuenta nueva.
    • Los usuarios existentes deben dirigirse a la página Configuración de Analytics y hacer clic en Agregar vista del sitio web (perfil). (Asegúrate de elegir dominio nuevo).
  2. En cualquiera de estas páginas, ingresa una URL de sitio web válida.
    3. Dado que la URL del sitio web es solo una cadena que el software de Google Analytics vincula con tu ID de dominio, esta URL puede ser cualquier cadena de URL del sitio web válida, ya sea falsa o real. No instalará el código de seguimiento en ninguna página web ni necesitará acceder a ninguna página del sitio web.
  3. Haz clic en el botón para continuar a la siguiente pantalla.
    4. Cuando aparezca el fragmento de código de seguimiento, copia el ID de dominio único en un bloc de notas. El fragmento de código generado automáticamente contiene este ID de dominio con el formato UA-123456-1.
  4. Haz clic en el botón Finalizar.
    5. Deberías ver el nombre de la URL de tu sitio web en la lista de vistas (perfil). También puede cambiar el nombre de la vista (perfil) por uno más significativo. Para ello, haga clic en el vínculo Editar de esa vista (perfil) y, luego, vuelva a hacer clic en Editar.
  5. Utiliza el ID de dominio generado en el código de seguimiento de tu gadget.
    6. Los IDs de dominio de Analytics tienen la siguiente forma:
    UA-123456-1
 

Seguimiento de tu gadget

El proceso de seguimiento de tu gadget implica tres incorporaciones al código del gadget:

  1. Se está habilitando la función.
  2. Crea un objeto de seguimiento.
  3. Realizar un seguimiento de tu gadget utilizando uno de estos dos métodos:

El siguiente ejemplo de código de gadget muestra cada una de estas adiciones de código, que luego se explican a continuación. Puedes utilizar este archivo de muestra para crear tu propio 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. Habilita la función

Primero, habilita la función importando la biblioteca de Analytics con el espacio de nombres de la función:

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

2. Cómo crear un objeto Tracker

La API de seguimiento de Analytics cumple con el mismo modelo orientado a objetos que el código de seguimiento ga.js. Por lo tanto, antes de realizar el seguimiento de tu gadget, crea una instancia de un objeto de seguimiento:

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

Aquí es donde insertarás el ID de dominio generado siguiendo los pasos anteriores.

Debes utilizar el ID de dominio completo con el número único final; de lo contrario, la llamada al objeto de seguimiento fallará.

3. Seguimiento de tu gadget

La API de gadgets ofrece dos métodos que puedes usar para realizar un seguimiento de la interacción con tus gadgets:

  • El método de URL virtual
    • ga.reportPageview(path);

    Este método realiza un seguimiento de las estadísticas de los gadgets como vistas especiales de páginas y es el mismo método utilizado en la versión anterior de la API de gadget de Analytics. Con este método, puedes actualizar el código de seguimiento de cualquier gadget preexistente sin afectar el diseño actual de tus informes de Analytics. Puedes ver los datos de los informes en tus gadgets del mismo modo que ves los datos de los informes de las páginas web.

    Cuando se utiliza el método de URL virtual para realizar un seguimiento de la interacción con un gadget, cada llamada se registra como una solicitud de página para la cadena que proporcionas como parámetro al método. Puedes aprovechar este comportamiento para pasar una ruta de URL inventada y ver los informes de los gadgets en la interfaz de Google Analytics tal como lo harías con los informes de páginas de sitios web. Por ejemplo, puedes usar rutas separadas para realizar un seguimiento de las vistas de los gadgets y de las interacciones con ellos: 

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

  • El método de seguimiento de eventos
    • ga.reportEvent(name, action, [[]label], [[]value]);

    Este método solo está disponible en la nueva API del gadget de Analytics. Con este método, puedes realizar un seguimiento de las páginas vistas (por ejemplo, la renderización del gadget) independientemente de las interacciones del usuario en tu gadget.

    Nota: En este momento, el seguimiento de eventos se encuentra en versión beta cerrada. Usa el método de URL virtual si no tienes acceso al seguimiento de eventos.

    El método de evento te ofrece un modelo diferente para que uses con el seguimiento de gadgets. En primer lugar, las llamadas a eventos se calculan por separado de las llamadas a vistas de página, y los datos resultantes se muestran en una parte separada de los informes de contenido de Google Analytics. Por lo tanto, puedes hacer un seguimiento de la vista de un gadget por separado de las interacciones del usuario en él, sin que esta interacción aumente la cantidad total de vistas del gadget. En segundo lugar, este método emplea el modelo de seguimiento de eventos, cuya estructura está diseñada específicamente para analizar la interacción de los usuarios en los gadgets. En este modelo, la etiqueta y el valor son parámetros opcionales.

    En el ejemplo de los contadores, podemos usar el método event para realizar un seguimiento de las funciones de los gadgets que se activan, y podemos pasar el tipo de control, que es un botón en ambos casos. 

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

    Este es un ejemplo muy sencillo, pero el modelo de seguimiento de eventos es una estructura altamente flexible que puedes definir mejor para aprovechar los requisitos de seguimiento exclusivos de tu gadget. Para obtener más información, consulta la documentación sobre cómo hacer un seguimiento de eventos.

 

Métodos de seguimiento

Actualmente, la función de Analytics ofrece los siguientes métodos. Su uso se discutió anteriormente.

  • reportPageview()
    • Requiere una cadena para propagar correctamente los informes de contenido. Por lo general, esta cadena tiene el formato de una ruta que defines para tus propósitos de generación de informes. El valor que se pasa a este método se envía en la solicitud GIF a través de la variable utmp. Utiliza este método para realizar un seguimiento de las cargas de gadgets y de sus interacciones. 
    ga.reportPageview("/view/gadgetName");
    parámetros
    String  path Es la ruta de acceso que se proporciona para la URL virtual de este elemento.

  • reportEvent()
    • Requiere el nombre del gadget y del parámetro de acción para poder insertar correctamente los datos con seguimiento en los informes de seguimiento de eventos. Los otros parámetros son opcionales. Los valores que se pasan a través de este método se envían en la vista de solicitud GIF y en la variable utme.

    parámetros
    String  name  Obligatorio.Es una cadena que se utiliza en el nivel superior de los informes de seguimiento de eventos. Por ejemplo, si estás realizando un seguimiento de la interacción en varios elementos de un gadget, probablemente deberías usar el nombre del gadget para este parámetro, de modo que todo el seguimiento de interacciones con el gadget se agregue a la misma sección de los informes de Google Analytics.

    String  action  Obligatorio. Esta es una cadena para segmentar aún más la interacción con el gadget en los informes de seguimiento de eventos. Para obtener más información, consulta la documentación sobre cómo hacer un seguimiento de eventos.

    String  label  Opcional. Cadena que puedes usar como segmento secundario del gadget.

    Int  value  Opcional. Es el número que puedes proporcionar como valor para la interacción del gadget. Este número se suma cada vez que se invoca el método.

 

Consideraciones de uso

La API de gadget de Google Analytics tiene varias consideraciones de uso:

  • Contenedores compatibles
    • Muchos tipos de contenedores son compatibles con la API de gadgets de Google Analytics, incluidos, sin limitaciones:
    • iGoogle
    • Distribución abierta
    • Open Social
    • Aparatos
  • Tipos de gadgets no compatibles
    • La API de gadgets de Google Analytics no admite los siguientes tipos de gadgets:
    • Widgets integrados (type=html-inline)
    • Mapplets
    • Widgets de tipo de URL (type-url)
    • Anuncios de gadget en Google AdSense
  • Consideraciones del dominio
    • Si necesitas la función de Analytics para tu gadget, este te redireccionará a <subdomain>.gmodules.com, donde <subdomain> es un subdominio único y aleatorio. Por lo tanto, todo el contenido del gadget se muestra bajo ese subdominio. Ejemplo: 3nvma227-a.gmodules.com. Además, todas las cookies de seguimiento de Google Analytics se configuran en este subdominio único. Por esta razón, la función de seguimiento de Analytics no admite mapplets, y debes permitir específicamente que el contenido Flash tenga acceso especial a la función de seguimiento (consulta a continuación).
  • Widgets con contenido Flash
    • Los gadgets que utilizan contenido Flash deben permitir específicamente la comunicación entre la URL Flash y la URL del gadget estableciendo el parámetro allowScriptAccess en "siempre". 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

Sugerencia

Cuál es la mejor manera de utilizar el método de URL virtual

Si no tienes acceso al método de seguimiento de eventos para tus gadgets, sigue estas recomendaciones para realizar un seguimiento de tus gadgets con el método de URL virtual:

  • Segmenta la carga de tu gadget de forma distintiva.
    • Puedes llamar a ga.reportPageview() durante la carga del gadget para especificar una ruta que segmente las estadísticas de carga o visualización del gadget por separado de las métricas de interacción. De esta forma, los datos de los informes de contenido del gadget se mantendrán en un "directorio" separado de las interacciones en el gadget, de modo que puedas ver las vistas generales por separado del número de interacciones en el gadget. Por ejemplo, puedes usar el siguiente fragmento de código en tu gadget para mostrar todas las estadísticas de carga de este: 
      ga.reportPageview('/view/gadgetName');
  • Segmenta los diferentes tipos de interacciones entre sí.
    • Llama a ga.reportPageview() con una ruta que segmente las diferentes interacciones del usuario. De esta manera, puedes obtener informes de contenido independientes para los vínculos de gadgets, los botones de gadgets u otros widgets de los que podrías querer realizar un seguimiento para ver los datos de interacción. Por ejemplo:
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

Cómo utilizar el método de seguimiento de eventos

Si tienes acceso a la función de seguimiento de eventos en los informes de Google Analytics, puedes aprovechar el modelo de datos altamente flexible para aprovechar al máximo el seguimiento de tus objetos. Aquí encontrarás algunas sugerencias:

  • Haz un seguimiento de la vista o la impresión del gadget con ga.reportPageview() y de las interacciones del gadget con ga.reportEvent().
    • Las vistas de gadget se mostrarán en la sección Contenido para los datos de la página, mientras que las interacciones de los gadgets se mostrarán en la sección Eventos de los Informes de contenido.
  • Utiliza document.referrer como parámetro para saber dónde se colocó tu gadget.
    • En el gadget, document.referrer suele ser la URL de la página del contenedor, por lo que puedes pasarla como un parámetro de etiqueta en el método ga.reportEvent():
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Solución de problemas

Puedes usar herramientas de terceros para analizar la cadena de solicitud de GIF de tu gadget y verificar que los datos se envíen a los informes de Google Analytics de la manera que esperas. Una vez que el gadget esté alojado correctamente y funcione en la página de prueba, analiza la cadena de solicitud de GIF de la siguiente manera:

  • Método de vistas de página
    • Busca la variable utmp en los parámetros de solicitud de GIF. La información asociada con esa variable es la que se enviará a los informes de Google Analytics como la "ruta" del gadget.
  • Método de seguimiento de eventos
    • Busca la variable UTM en los parámetros de solicitud de GIF. Esta información debe tener el formato 5(object*action*label)(value).

Para obtener más información sobre cómo solucionar problemas con el código de seguimiento, consulta la Guía de solución de problemas de GATC.