En este documento se proporciona una visión general de la biblioteca de recopilación de datos de analytics.js.
Fragmento de JavaScript
Para habilitar Google Analytics en tu sitio web, debes agregar un fragmento JavaScript antes de la etiqueta </head> de cierre de la página. Esta es una parte del fragmento:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
Cuando se ejecuta el fragmento, en primer lugar crea una nueva función global denominada ga.
A continuación, el fragmento carga de forma asíncrona la biblioteca analytics.js en la página.
La función global ga es el modo principal de interactuar con la biblioteca analytics.js. La función acepta una secuencia de parámetros, donde el primero representa un comando de Google Analytics. Por ejemplo, en el fragmento predeterminado:
ga('create', 'UA-XXXX-Y', 'auto'); // Creates a tracker.
ga('send', 'pageview'); // Sends a pageview.
La primera línea llama al comando create y, la segunda, send.
Aunque el código JavaScript carga la biblioteca analytics.js de forma asíncrona, la función ga se ha diseñado para usarse antes de que se cargue la biblioteca. Al empezar a ejecutar los comandos por primera vez, cada uno se agrega a una cola. Cuando la biblioteca termina de cargarse, se ejecutan todos los comandos de la cola y los comandos nuevos se ejecutan inmediatamente. De este modo, los programadores pueden ignorar la naturaleza asíncrona de Google Analytics y centrarse en el uso de la función ga.
Cambiar el nombre del objeto global
En algunos casos, es posible que un objeto de la página ya esté usando el nombre de la variable ga. Para evitar que se anule el objeto, puedes cambiar el nombre de la función ga, por ejemplo, a __gaTracker.
Para ello, solo tienes que reemplazar el parámetro ga en el fragmento anterior:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','__gaTracker');
Después, puedes usar __gaTracker en vez de ga para llamar a los comandos:
__gaTracker('create', 'UA-XXXX-Y', 'auto');
__gaTracker('send', 'pageview');
Referencia del fragmento JavaScript
En la siguiente referencia se muestra el fragmento JavaScript básico, al que se han agregado comentarios y espacios en blanco:
<!-- Google Analytics -->
<script>
/**
* Creates a temporary global ga object and loads analy tics.js.
* Paramenters o, a, and m are all used internally. They could have been declared using 'var',
* instead they are declared as parameters to save 4 bytes ('var ').
*
* @param {Window} i The global context object.
* @param {Document} s The DOM document object.
* @param {string} o Must be 'script'.
* @param {string} g URL of the analytics.js script. Inherits protocol from page.
* @param {string} r Global name of analytics object. Defaults to 'ga'.
* @param {DOMElement?} a Async script tag.
* @param {DOMElement?} m First script tag in document.
*/
(function(i, s, o, g, r, a, m){
i['GoogleAnalyticsObject'] = r; // Acts as a pointer to support renaming.
// Creates an initial ga() function. The queued commands will be executed once analytics.js loads.
i[r] = i[r] || function() {
(i[r].q = i[r].q || []).push(arguments)
},
// Sets the time (as an integer) this tag was executed. Used for timing hits.
i[r].l = 1 * new Date();
// Insert the script tag asynchronously. Inserts above current tag to prevent blocking in
// addition to using the async attribute.
a = s.createElement(o),
m = s.getElementsByTagName(o)[0];
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m)
})(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-XXXX-Y', 'auto'); // Creates the tracker with default parameters.
ga('send', 'pageview'); // Sends a pageview hit.
</script>
<!-- End Google Analytics -->
Fragmento asíncrono alternativo
Aunque el fragmento analytics.js canónico descrito anteriormente garantiza que la secuencia de comandos se cargará y ejecutará de forma asíncrona en todos los navegadores, tiene la desventaja de no permitir que los navegadores modernos realicen una carga previa de la secuencia de comandos.
El fragmento alternativo siguiente agrega compatibilidad de la carga previa, lo que proporciona un pequeño impulso de rendimiento en los navegadores modernos, pero se puede deteriorar en la carga síncrona y en la ejecución en IE9 y en navegadores para dispositivos móviles anteriores, que no reconocen el atributo async. Te sugerimos que uses este fragmento si tus visitantes utilizan principalmente navegadores modernos para acceder a tu sitio.
<!-- Google Analytics -->
<script async src='//www.google-analytics.com/analytics.js'></script>
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->
Crear objetos de seguimiento
Para enviar datos a Google Analytics, debes crear un objeto de seguimiento. Cada uno de estos objetos puede enviar datos a una sola propiedad web de Google Analytics. Para crear un objeto de seguimiento, el fragmento predeterminado usa el siguiente código:
ga('create', 'UA-XXXX-Y', 'auto');
Donde el primer parámetro de la función ga es el comando create y el segundo es el ID de propiedad web al que se enviarán los datos.
Personalizar los objetos de seguimiento
La personalización del objeto de seguimiento se debe llevar a cabo cuando se crea inicialmente, pasando a la función ga un objeto de configuración como el último parámetro. Por ejemplo, para anular algunas de las opciones de configuración de la cookie, se usa:
ga('create', 'UA-12345-6', {
'cookieDomain': 'foo.example.com',
'cookieName': 'myNewName',
'cookieExpires': 20000
});
En el ejemplo anterior, el dominio, el nombre y el tiempo de caducidad de la cookie se han modificado mediante el objeto de configuración opcional.
Consulta la sección solo del comando create del documento Referencia de campos para obtener información completa sobre todos los campos que se pueden configurar en el comando create.
Pruebas en localhost
En algunos casos, puedes probar analytics.js desde un servidor web que se ejecute en localhost. Para configurar las cookies de analytics.js, debes inhabilitar el dominio de cookie predeterminado mediante:
ga('create', 'UA-XXXX-Y', {
'cookieDomain': 'none'
});
Enviar datos
Una vez que un objeto de seguimiento se ha creado y asociado a una propiedad web, puedes usar el comando send para enviar datos a dicha propiedad web.
Los datos que envíes a Google Analytics se denominan hit y la biblioteca analytics.js te permite enviar varios tipos de datos especificando un tipo de hit (hitType). Al usar el comando send, también debes especificar el valor de hitType de los datos que quieras enviar.
Por ejemplo, para enviar un hit de página vista, se usa:
ga('send', 'pageview');
De este modo, se envían datos para la URL predeterminada a Google Analytics.
Objeto de nombre de campo
En algunos casos, puedes anular varios valores que se envían como una página vista. La biblioteca analytics.js te permite enviar un objeto de nombre de campo como el último parámetro del comando send. Esto resulta útil ya que te permite establecer muchas propiedades adicionales de la página vista, por ejemplo, su título:
ga('send', 'pageview', {
'page': '/my-new-page',
'title': 'My New Page Title'
});
Consulta el documento Referencia de los campos para obtener información completa sobre todas las formas en que se puede configurar un objeto de seguimiento.
Configurar la devolución de llamada del hit
En algunos casos, por ejemplo, al realizar el seguimiento de los enlaces de salida, se puede saber cuándo ha terminado el objeto de seguimiento de enviar los datos. De este modo, puedes enviar a un usuario a su destino solo después de que su clic se haya comunicado a Google Analytics. Para resolver esta situación, el comando send te permite especificar una función hitCallback en el objeto de nombre de campo que se ejecutará en cuanto analytics.js haya terminado de enviar los datos.
A continuación, te mostramos la forma de configurar la función hitCallback:
ga('send', 'pageview', {
'page': '/my-new-page',
'hitCallback': function() {
alert('analytics.js done sending data');
}
});
En este ejemplo, el objeto de nombre de campo configura el parámetro page y la función hitCallback.
Después de que el objeto de seguimiento haya terminado de enviar los datos, se mostrará un cuadro de alerta al usuario.
Configurar los parámetros en varios comandos send
En algunos casos, es recomendable establecer un parámetro y que el valor se mantenga en varios comandos send. Por ejemplo, si tienes una página web de la que deseas realizar el seguimiento de una página vista y dos eventos. Si quisieras anular la ruta de la página de cada hit por una tuya, podrás establecer la nueva ruta en cada comando send o usar el método set del siguiente modo:
ga('set', 'page', '/my-custom-page');
ga('send', 'pageview');
ga('send', 'event', 'image1', 'clicked');
ga('send', 'event', 'image2', 'clicked');
Cuando se ejecuta este código, la página sustituida /my-custom-page se enviará a los tres comandos send.
Enviar hits useBeacon
Para enviar hits con
navigator.sendBeacon, configura el parámetro
useBeacon como true.
El método navigator.sendBeacon garantiza que los datos se transmiten incluso si el usuario sale de tu página o cierra el navegador antes de que se haya completado la solicitud. Esto resulta muy útil en los casos en los que deseas realizar el seguimiento de un evento antes de que un usuario salga de tu sitio, sin retrasar la navegación.
ga('send', 'event', 'click', 'download-me', {useBeacon: true});
Transmitir funciones
En ocasiones, el código se ejecuta solo después de que se haya cargado la biblioteca analytics.js.
Para ello, puedes enviar una función como un parámetro a la función ga.
ga(function() {
alert('library done loading');
});
Cuando se termine de cargar la biblioteca, el usuario verá un cuadro de alerta.
Obtener parámetros
Con analytics.js, se puede recuperar cualquiera de los valores que se han configurado en el objeto de seguimiento mediante el comando get. Puesto que el objeto de seguimiento solo se crea cuando se ha cargado la biblioteca, debes obtener parámetros desde una función enviada.
ga(function(tracker) {
var defaultPage = tracker.get('page');
});
En este ejemplo, la función usa un parámetro denominado tracker.
Cuando termina la carga de la biblioteca, la función se ejecuta y el valor de tracker será el objeto de seguimiento predeterminado que se ha creado como resultado del primer comando create. Después, el objeto tracker se usa para obtener el valor de página predeterminado.
Aplicar SSL (HTTPS)
"De forma predeterminada, Google Analytics se ajustará al protocolo de la página host al enviar las solicitudes de salida. Para forzar que Google Analytics siempre envíe datos mediante SSL, incluso desde páginas no seguras (HTTP), configura el campo forceSSL como true:
ga('create', 'UA-XXXX-Y', 'auto');
ga('set', 'forceSSL', true); // Send all data using SSL, even from insecure (HTTP) pages.
ga('send', 'pageview');
Trabajar con varios objetos de seguimiento
En algunos casos es recomendable enviar los datos a varias propiedades web desde una sola página. Esto resulta útil para sitios que tienen varios propietarios que supervisan determinadas secciones de un sitio; cada propietario podría ver su propiedad web.
Para solucionar este problema, debes crear un objeto de seguimiento por cada propiedad web a la que quieras enviar datos:
ga('create', 'UA-XXXX-Y', 'auto');
ga('create', 'UA-12345-6', 'auto', {'name': 'newTracker'}); // New tracker.
Cuando se ejecute, se crearán dos objetos de seguimiento. El primero será el predeterminado y no tendrá nombre. El segundo se llamará newTracker.
Para enviar una página vista con ambos objetos de seguimiento, debes anteponer el nombre del objeto de seguimiento al comando, seguido de un punto. Por ejemplo:
ga('send', 'pageview');
ga('newTracker.send', 'pageview'); // Send page view for new tracker.
Se enviará una página vista tanto al objeto de seguimiento predeterminado como al nuevo.
Para acceder al objeto de seguimiento por nombre desde una función, usa el método getByName:
ga(function() {
var newTracker = ga.getByName('newTracker');
});
Para obtener una matriz de todos los objetos de seguimiento que se han configurado, usa el método getAll:
ga(function() {
var allTrackers = ga.getAll();
});
Atribución de enlace mejorada
Con la atribución de enlace mejorada se incrementa la precisión del informe Analítica en página mediante la diferenciación automática de varios enlaces a la misma URL de una sola página con los ID de elemento de enlace.
Para habilitar la atribución de enlace mejorada:
- Habilita la atribución de enlace mejorada en la interfaz de usuario de administración de la cuenta de Google Analytics.
- Actualiza el código de cada página para cargar el plugin de atribución de enlace mejorada, tal como se muestra en este ejemplo:
ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid'); // Load the plug-in. Note: this call will block until the plug-in is loaded.
ga('send', 'pageview');
Personalizar la atribución de enlace mejorada
El plugin de atribución de enlace mejorada distingue entre enlaces a la misma URL mediante los ID de elemento de un enlace o un elemento principal, así como una cookie. Puedes personalizar hasta dónde buscará el plugin en el DOM un ID de elemento, así como el comportamiento de esta cookie, proporcionando las opciones de configuración al cargar el plugin:
ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid', {
'cookieName': '_ela', // Cookie name. _gali by default.
'duration': 45, // Cookie duration. 30 seconds by default.
'levels': 5}); // Max DOM levels from link to look for element ID. 3 by default.
ga('send', 'pageview');
Convertir las IP en anónimas
En algunos casos, es posible que debas convertir en anónima la dirección IP del hit (solicitud http) que se envía a Google Analytics. Puedes convertir en anónimas las direcciones IP de todos los hits enviados desde una página (la duración del objeto de seguimiento) mediante el comando set y la configuración del campo anonymizeIp como true:
ga('set', 'anonymizeIp', true);
Para convertir en anónima la dirección IP de un hit individual, puedes configurar el campo anonymizeIp en el objeto de configuración opcional de dicho hit:
ga('send', 'pageview', {
'anonymizeIp': true
});
Para obtener más información sobre el funcionamiento de la conversión de las IP en anónimas, consulta el artículo Convertir las IP en anónimas en Google Analytics en el Centro de ayuda.
Inhabilitación del usuario
En algunos casos, puede ser necesario inhabilitar el código de seguimiento de Google Analytics en una página sin tener que suprimir el fragmento JavaScript. Por ejemplo, puedes hacerlo si la política de privacidad de tu sitio incluye la posibilidad de que un usuario inhabilite el seguimiento de Google Analytics.
La biblioteca analytics.js incluye una propiedad de ventana que, cuando se configura como true, inhabilita el envío de datos de analytics.js a Google Analytics.
Cuando Google Analytics intenta configurar una cookie o devolver datos a los servidores de Google Analytics, comprueba si esta propiedad se ha configurado como true. Si es así, tendrá el mismo efecto que si el usuario tiene instalado el plugin de inhabilitación para navegadores de Google Analytics.
Para inhabilitar el seguimiento, configura la siguiente propiedad de ventana como true:
window['ga-disable-UA-XXXX-Y'] = true;
Donde el valor UA-XXXX-Y corresponde al ID de propiedad web en el que deseas inhabilitar el seguimiento.
Esta propiedad de ventana se debe configurar antes de llamar al código de seguimiento. Esta propiedad se debe configurar en cada página donde desees inhabilitar el seguimiento de Google Analytics. Si la propiedad no está configurada o se ha configurado como false, el seguimiento funcionará de la forma habitual.
Ejemplo
A continuación, se muestra un ejemplo simple del código que puedes usar para ofrecer a los usuarios la funcionalidad de inhabilitación.
En primer lugar, agrega un nuevo enlace HTML al sitio para ejecutar la lógica de inhabilitación:
<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>
Después, agrega el siguiente fragmento de código antes del fragmento de código de analytics.js. No te olvides de reemplazar el valor UA-XXXX-Y de gaProperty por la propiedad usada en el sitio.
Se trata del mismo valor que se pasa al comando create.
<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>
Cuando un usuario hace clic en el enlace HTML de inhabilitación, se ejecuta la función gaOptout. Se configurará una cookie con una larga duración y se inhabilitará la recopilación de datos de analytics.js.
Cuando un usuario vuelva a este sitio, con la secuencia de comandos anterior se comprobará si se ha configurado la cookie de inhabilitación. En caso afirmativo, también se inhabilitará la recopilación de datos de analytics.js.
Depuración
Puedes habilitar la versión de depuración de analytics.js mediante analytics_debug.js:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics_debug.js','ga');
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');
Solo se debe usar temporalmente o durante el desarrollo, ya que analytics_debug.js es más grande y retrasará los hits a google-analytics.com.
Depuración de seguimiento
Con la depuración de seguimiento se enviará información más detallada a la consola. Para habilitar este tipo de depuración, utiliza https://www.google-analytics.com/analytics_debug.js y esta línea de código antes del fragmento:
window.ga_debug = {trace: true};