En aquest document es proporciona una visió general de la biblioteca de recopilació de dades de analytics.js.
Fragment de JavaScript
Per habilitar Google Analytics en el teu lloc web, has de afegir un fragment JavaScript abans de l’etiqueta </head> de tancament de la pàgina. Aquesta és una part de l’fragment:
(function(i,s,o,g,r,a,m){i=r;i=i||function(){(i.q=i.q||).push(arguments)},i.l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o);a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
Quan s’executa el fragment, en primer lloc crea una nova funció global anomenada ga. A continuació, el fragment càrrega de forma asíncrona la biblioteca analytics.js a la pàgina.
La funció global ga és la manera principal d’interactuar amb la biblioteca analytics .js. La funció accepta una seqüència de paràmetres, on el primer representa una ordre de Google Analytics. Per exemple, en el fragment predeterminat:
ga('create', 'UA-XXXX-Y', 'auto'); // Creates a tracker.ga('send', 'pageview'); // Sends a pageview.
La primera línia crida a la comanda create i, la segona, send.
Tot i que el codi JavaScript carrega la biblioteca analytics.js de forma asíncrona, la funció ga s’ha dissenyat per usar-se abans que es carregui la biblioteca. A l’començar a executar les ordres per primera vegada, cadascun s’afegeix a una cua. Quan la biblioteca acaba de carregar-se, s’executen tots els ordres de la cua i les ordres nous s’executen immediatament. D’aquesta manera, els programadors poden ignorar la naturalesa asíncrona de Google Analytics i centrar-se en l’ús de la funció ga.
Canviar el nom de l’objecte global
En alguns casos, és possible que un objecte de la pàgina ja estigui fent servir el nom de la variable ga. Per evitar que s’anul·li l’objecte, pots canviar el nom de la funció ga, per exemple, a __gaTracker. Per a això, només has de reemplaçar el paràmetre ga en el fragment anterior:
(function(i,s,o,g,r,a,m){i=r;i=i||function(){(i.q=i.q||).push(arguments)},i.l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o);a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','//www.google-analytics.com/analytics.js','__gaTracker');
Després, pots utilitzar __gaTracker en comptes de ga per cridar als comandaments:
__gaTracker('create', 'UA-XXXX-Y', 'auto');__gaTracker('send', 'pageview');
referència de l’fragment JavaScript
en la següent referència es mostra el fragment JavaScript bàsic, a què s’han afegit comentaris i espais en blanc:
<!-- 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 = r; // Acts as a pointer to support renaming. // Creates an initial ga() function. The queued commands will be executed once analytics.js loads. i = i || function() { (i.q = i.q || ).push(arguments) }, // Sets the time (as an integer) this tag was executed. Used for timing hits. i.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); 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 -->
fragment asíncron alternatiu
Tot i que el fragment analytics.js canònic descrit anteriorment garanteix que la seqüència de comandaments es carregarà i executarà de forma asíncrona en tots els navegadors, té el desavantatge de no permetre que els navegadors moderns realitzin una càrrega prèvia de la seqüència de comandaments.
El fragment alternatiu següent afegeix compatibilitat de la càrrega prèvia, el que proporciona un petit impuls de rendiment en els navegadors moderns, però es pot deteriorar en la càrrega síncrona i en l’execució en IE9 i en navegadors per a dispositius mòbils anteriors, que no reconeixen l’atribut async. Et suggerim que facis servir aquest fragment si els teus visitants utilitzen principalment navegadors moderns per accedir al teu lloc.
<!-- 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 objectes de seguiment
Per enviar dades a Google Analytics, has de crear un objecte de seguiment. Cada un d’aquests objectes pot enviar dades a una sola propietat web de Google Analytics. Per crear un objecte de seguiment, el fragment predeterminat fa servir el següent codi:
ga('create', 'UA-XXXX-Y', 'auto');
On el primer paràmetre de la funció ga és la comanda create i el segon és l’ID de propietat web a què s’enviaran les dades.
Personalitzar els objectes de seguiment
la personalització de l’objecte de seguiment s’ha de dur a terme quan es crea inicialment, passant a la funció ga un objecte de configuració com l’últim paràmetre. Per exemple, per anul·lar algunes de les opcions de configuració de la galeta, s’usa:
ga('create', 'UA-12345-6', { 'cookieDomain': 'foo.example.com', 'cookieName': 'myNewName', 'cookieExpires': 20000});
En l’exemple anterior, el domini, el nom i el temps de caducitat de la galeta s’han modificat mitjançant l’objecte de configuració opcional.
Consulta la secció només de la comanda create d’el document Referència de camps per obtenir informació completa sobre tots els camps que es poden configurar en la comanda create .
Proves a localhost
en alguns casos, pots provar analytics.js des d’un servidor web que s’executi en localhost. Per configurar les galetes de analytics.js, has desactivar el domini de galeta predeterminat mitjançant:
ga('create', 'UA-XXXX-Y', { 'cookieDomain': 'none'});
Enviar dades
Una vegada que un objecte de seguiment s’ha creat i associat a una propietat web, pots utilitzar la comanda send per enviar dades a aquesta propietat web. Les dades que envies a Google Analytics s’anomenen hit i la biblioteca analytics.js et permet enviar diversos tipus de dades especificant un tipus de hit (hitType). A l’utilitzar la comanda send, també has d’especificar el valor de hitType de les dades que vulguis enviar.
Per exemple, per enviar un hit de pàgina vista, s’usa:
ga('send', 'pageview');
d’aquesta manera, s’envien dades per a la URL predeterminada a Google Analytics.
Objecte de nom de camp
En alguns casos, pots anul·lar diversos valors que s’envien com una pàgina vista. La biblioteca analytics.js et permet enviar un objecte de nom de camp com l’últim paràmetre de la comanda send. Això resulta útil ja que et permet establir moltes propietats addicionals de la pàgina vista, per exemple, el seu títol:
ga('send', 'pageview', { 'page': '/my-new-page', 'title': 'My New Page Title'});
Consulta el document Referència dels camps per obtenir informació completa sobre totes les formes en què es pot configurar un objecte de seguiment.
Configura la devolució de trucada de l’hit
en alguns casos, per exemple, a l’realitzar el seguiment dels enllaços de sortida, es pot saber quan ha acabat l’objecte de seguiment d’enviar les dades. D’aquesta manera, pots enviar a un usuari al seu destí només després que el seu clic s’hagi comunicat a Google Analytics. Per resoldre aquesta situació, la comanda send et permet especificar una funció hitCallback en l’objecte de nom de camp que s’executarà pel que fa analytics. js hagi acabat d’enviar les dades. A continuació, et mostrem la forma de configurar la funció hitCallback:
ga('send', 'pageview', { 'page': '/my-new-page', 'hitCallback': function() { alert('analytics.js done sending data'); }});
En aquest exemple, l’objecte d’ nom de camp configura el paràmetre page i la funció hitCallback. Després que l’objecte de seguiment hagi acabat d’enviar les dades, es mostrarà un quadre d’alerta a l’usuari.
Configura els paràmetres en diversos ordres send
En alguns casos, és recomanable establir un paràmetre i que el valor es mantingui en diversos ordres send. Per exemple, si tens una pàgina web de la qual vols fer el seguiment d’una pàgina vista i dos esdeveniments. Si volguessis anul·lar la ruta de la pàgina de cada hit per una teva, podràs establir la nova ruta en cada comanda send o utilitzar el mètode set de la següent forma:
ga('set', 'page', '/my-custom-page');ga('send', 'pageview');ga('send', 'event', 'image1', 'clicked');ga('send', 'event', 'image2', 'clicked');
Quan s’executa aquest codi, la pàgina substituïda /my-custom-page s’enviarà als tres ordres send.
Enviar hits useBeacon
Per enviar hits amb navigator.sendBeacon, configura el paràmetre useBeacon com true. El mètode navigator.sendBeacon garanteix que les dades es transmeten fins i tot si l’usuari surt de la teva pàgina o tanca el navegador abans que s’hagi completat la sol·licitud. Això resulta molt útil en els casos en què vols fer el seguiment d’un esdeveniment abans que un usuari surti del teu lloc, sense retardar la navegació.
ga('send', 'event', 'click', 'download-me', {useBeacon: true});
Transmetre funcions
de vegades, el codi s’executa només després que s’hagi carregat la biblioteca analytics.js. Per a això, pots enviar una funció com un paràmetre a la funció ga.
ga(function() { alert('library done loading');});
Quan s’acabi de carregar la biblioteca, l’usuari veurà un quadre d’alerta.
Obtenir paràmetres
Amb analytics.js, es pot recuperar qualsevol dels valors que s’han configurat en l’objecte de seguiment mitjançant el ordre get. Ja que l’objecte de seguiment només es crea quan s’ha carregat la biblioteca, has d’obtenir paràmetres des d’una funció enviada.
ga(function(tracker) { var defaultPage = tracker.get('page');});
En aquest exemple, la funció utilitza un paràmetre anomenat tracker. Quan acaba la càrrega de la biblioteca, la funció s’executa i el valor de tracker serà l’objecte de seguiment per defecte que s’ha creat com a resultat de la primera ordre create. Després, l’objecte tracker s’usa per obtenir el valor de pàgina per defecte.
Aplicar SSL (HTTPS)
“Per defecte, Google Analytics s’ajustarà a el protocol de la pàgina host a l’enviar les sol·licituds de sortida.Per forçar que Google Analytics sempre enviï dades mitjançant SSL, fins i tot des de pàgines no segures (HTTP), configura el camp forceSSL com true:
ga('create', 'UA-XXXX-Y', 'auto');ga('set', 'forceSSL', true); // Send all data using SSL, even from insecure (HTTP) pages.ga('send', 'pageview');
Treballar amb diversos objectes de seguiment
En alguns casos és recomanable enviar les dades a diverses propietats web des d’una sola pàgina. Això és útil per a llocs que tenen diversos propietaris que supervisen determinades seccions d’un lloc; cada propietari podria veure la seva propietat web.
Per solucionar aquest problema, has de crear un objecte de seguiment per cada propietat web a la que vulguis enviar dades:
ga('create', 'UA-XXXX-Y', 'auto');ga('create', 'UA-12345-6', 'auto', {'name': 'newTracker'}); // New tracker.
Quan s’executi, es crearan dos objectes de seguiment. El primer serà el predeterminat i no tindrà nom. El segon es dirà newTracker.
Per enviar una pàgina vista amb els dos objectes de seguiment, has anteposar el nom de l’objecte de seguiment a la comanda, seguit d’un punt . Per exemple:
ga('send', 'pageview');ga('newTracker.send', 'pageview'); // Send page view for new tracker.
S’ha d’enviar una pàgina vista tant a l’objecte de seguiment per defecte com a el nou.
Per accedir a l’objecte de seguiment per nom des d’una funció, fa servir el mètode getByName:
ga(function() { var newTracker = ga.getByName('newTracker');});
per obtenir una matriu de tots els objectes de seguiment que s’han configurat, fa servir el mètode getAll:
ga(function() { var allTrackers = ga.getAll();});
Reconeixement d’enllaç millorada
amb l’atribució d’enllaç millorada s’incrementa la precisió de l’informe Analítica a pàgina mitjançant la diferenciació automàtica de diversos enllaços a la mateixa URL d’una sola pàgina amb els ID d’element d’enllaç.
Per habilitar la atribució d’enllaç millorada:
- Activa l’atribució d’enllaç millorada en la interfície d’usuari d’administració del compte d’Analytics.
- Actualitza el codi de cada pàgina per carregar el connector d’atribució d’enllaç millorada, tal com es mostra en aquest exemple:
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');
Personalitzar l’atribució d’enllaç millorada
El connector d’atribució d’enllaç millorada distingeix entre enllaços a la mateixa URL mitjançant els ID d’element d’un enllaç o un element principal, així com una galeta. Pots personalitzar fins on buscarà el connector al DOM un ID d’element, així com el comportament d’aquesta galeta, proporcionant les opcions de configuració a l’carregar el connector:
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 les IP en anònimes
en alguns casos, és possible que hagis de convertir en anònima l’adreça IP de l’hit (sol·licitud http) que s’envia a Google Analytics. Pots convertir en anònimes les adreces IP de tots els hits enviats des de la pàgina (la durada de l’objecte de seguiment) mitjançant la comanda set i la configuració de camp anonymizeIp com true:
ga('set', 'anonymizeIp', true);
Per convertir en anònima l’adreça IP d’un hit individual, pots configurar el camp anonymizeIp en l’objecte de configuració opcional d’aquest hit:
ga('send', 'pageview', { 'anonymizeIp': true});
Per obtenir més informació sobre el funcionament de la conversió de les IP en anònimes, consulta l’article Convertir les IP a anònimes a Google Analytics al Centre d’ajuda.
Inhabilitació de l’usuari
en alguns casos, pot ser necessari desactivar el codi de seguiment de Google Analytics a una pàgina sense haver de suprimir el fragment JavaScript. Per exemple, pots fer-ho si la política de privacitat del teu lloc inclou la possibilitat que un usuari inhabiliti el seguiment de Google Analytics.
La biblioteca analytics.js inclou una propietat de finestra que, quan es configura com true, inhabilita l’enviament de dades de analytics.js a Google Analytics. Quan Google Analytics intenta configurar una galeta o retornar dades als servidors de Google Analytics, comprova si aquesta propietat s’ha configurat com true. Si és així, tindrà el mateix efecte que si l’usuari té instal·lat el plugin d’inhabilitació per a navegadors de Google Analytics.
Per desactivar el seguiment, configura la següent propietat de finestra com true:
window = true;
on el valor UA-XXXX-Y correspon a l’identificador de propietat web en el qual desitges desactivar el seguiment.
Aquesta propietat de finestra s’ha de configurar abans de cridar a el codi de seguiment. Aquesta propietat s’ha de configurar a cada pàgina on vulguis desactivar el seguiment de Google Analytics. Si la propietat no està configurada o s’ha configurat com false, el seguiment funcionarà de la forma habitual.
Exemple
A continuació, es mostra un exemple simple de el codi que pots utilitzar per oferir als usuaris la funcionalitat d’inhabilitació.
En primer lloc, afegeix un nou enllaç HTML a el lloc per executar la lògica d’inhabilitació:
<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>
Després, afegeix el següent fragment de codi abans de l’fragment de codi de analytics.js. No t’oblidis de reemplaçar el valor UA-XXXX-Y de gaProperty per la propietat usada en el lloc. Es tracta del mateix valor que es passa a l’ordre create.
<script>// Set to the same value as the web property used on the sitevar 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 = true;}// Opt-out functionfunction gaOptout() { document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/'; window = true;}</script>
Quan un usuari fa clic a l’enllaç HTML d’inhabilitació, s’executa la funció gaOptout. Es configurarà una galeta amb una llarga durada i s’inhabilitarà la recopilació de dades de analytics.js. Quan un usuari torni a aquest lloc, amb la seqüència de comandaments anterior es comprovarà si s’ha configurat la galeta d’inhabilitació. En cas afirmatiu, també es desactivarà la recopilació de dades de analytics.js.
Depuració
Pots habilitar la versió de depuració de analytics.js mitjançant analytics_debug.js:
(function(i,s,o,g,r,a,m){i=r;i=i||function(){(i.q=i.q||).push(arguments)},i.l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o);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');
Només s’ha d’usar temporalment o durant el desenvolupament, ja que analytics_debug.js és més gran i endarrerirà els hits a google-analytics.com.
depuració de seguiment
Amb la depuració de seguiment s’enviarà informació més detallada a la consola. Per habilitar aquest tipus de depuració, utilitza https://www.google-analytics.com/analytics_debug.js i aquesta línia de codi abans de l’fragment:
window.ga_debug = {trace: true};