La cola de comandos ga()
proporciona una interfaz para prácticamente todo lo que necesitas hacer con la biblioteca analytics.js.
El fragmento de seguimiento JavaScript define la función inicial de la cola de comandos ga()
, por lo que se puede usar incluso antes de que la biblioteca analytics.js se cargue por completo. En cuanto se carga la biblioteca analytics.js, se ejecutan los elementos de la cola de comandos en el orden en que se han recibido. Una vez finalizada esta operación, los nuevos comandos que se envíen a la cola se ejecutarán inmediatamente.
Para que el fragmento de seguimiento sea lo más pequeño posible, la cola de comandos de ga()
se sobrecarga para aceptar argumentos en diferentes formatos. En este documento se explican las diferentes formas en que se puede invocar la función de la cola de comandos de ga()
.
Firma de función | |
---|---|
ga(command, [...fields], [fieldsObject]) |
Si se invoca la función de cola de comandos |
ga(readyCallback) |
Si se invoca la función de cola de comandos Como los comandos solo se ejecutan después de que la biblioteca analytics.js esté totalmente cargada, el motivo más habitual para transmitir una función a la cola de comandos es usarla como retrollamada cuando la biblioteca analytics.js esté cargada y preparada. |
Añadir comandos a la cola
Si se invoca la función de cola de comandos ga()
con la siguiente firma de función, se enviarán los comandos a la cola para programar su ejecución una vez que se haya cargado la biblioteca.
Uso
ga(command, [...fields], [fieldsObject])
Parámetros
Nombre | Tipo | Obligatorio | Descripción | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
command |
string |
sí |
Identificador que representa el comando que se agregará a la cola. El identificador está formado por tres partes (las dos primeras son opcionales): [trackerName.][pluginName:]methodName
|
|||||||||
...fields |
* |
No | Uno o varios parámetros auxiliares opcionales para especificar rápidamente los campos comunes. El número de los campos específicos que se permiten varía según el método de comando al que se llame. | |||||||||
fieldsObject |
Object |
no |
Objeto para especificar los valores restantes que no se indican en ninguno de los parámetros de Si se configura un campo en el parámetro |
En la referencia de campos puedes consultar la documentación de cada campo.
Ejemplos
Puedes consultar ejemplos de comando en la sección de métodos de comando siguiente.
Ready callback
Si se invoca la función de cola de comandos ga()
transmitiéndole una función, se programará la ejecución de la función transmitida en el siguiente punto de la cola.
Como los comandos solo se ejecutan después de que la biblioteca analytics.js esté totalmente cargada, el motivo más habitual para transmitir una función a la cola de comandos es usarla como retrollamada cuando la biblioteca analytics.js esté cargada y preparada.
Uso
ga(readyCallback)
Parámetros
Nombre | Tipo | Obligatorio | Descripción |
---|---|---|---|
readyCallback |
Function |
sí |
Función de devolución de llamada que se invocará cuando la biblioteca esté totalmente cargada y preparada para interactuar con ella. El primer argumento con el que se invoca la función es el objeto de seguimiento predeterminado. Si no se ha creado este objeto, el primer argumento es Nota: Cuando se invoca la función de retrollamada, pueden usarse todos los métodos del objeto
|
Ejemplos
// Queues a tracker object for creation. ga('create', 'UA-XXXXX-Y', 'auto'); // Once the tracker has been created, log the // client ID to the console. ga(function(tracker) { console.log(tracker.get('clientId')); });
// Queues a named tracker object for creation. ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker'); // When there is no default tracker, the first // argument of the ready callback is `undefined`. ga(function(tracker) { console.log(tracker); // Logs `undefined`. });
Detalles de método de comando
A continuación, se incluye una lista con todos los métodos que se pueden transferir a la cola de comandos de ga()
, excepto los métodos de complemento.
create
Crea una instancia de objeto de seguimiento con los campos especificados.
Uso
ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);
Parámetros
En la referencia de campos puedes consultar la documentación de cada campo.
Devuelve
undefined
Ejemplos
// Creates a default tracker for the Property UA-XXXXX-Y // and uses automatic cookie domain configuration. ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property // UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies // a transport mechanism of "beacon". ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', { transport: 'beacon' });
send
Envía un hit a Google Analytics.
Uso
ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);
Los campos que se envían son los valores especificados en los parámetros ...fields
y en fieldsObject
, y se combinan con los campos que están almacenados en el objeto de seguimiento.
Parámetros
Los campos que se pueden especificar con los parámetros ...fields
varían según el tipo de hit. En la tabla siguiente se enumeran los campos que corresponden a cada tipo de hit. Los tipos de hit que no aparecen en la tabla no aceptan los parámetros ...fields
, solo fieldsObject
.
Tipo de hit | ...fields |
---|---|
pageview |
page |
event |
eventCategory , eventAction , eventLabel y eventValue |
social |
socialNetwork , socialAction y socialTarget |
timing |
timingCategory , timingVar , timingValue y timingLabel |
En la referencia de campos puedes consultar la documentación de cada campo.
Devuelve
undefined
Ejemplos
// Sends a pageview hit. ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the // following category, action, and label, and sets the nonInteraction // field value to true. ga('send', 'event', 'link', 'click', 'http://example.com', { nonInteraction: true });
set
Permite configurar un solo par de campo y valor o un grupo de pares de campo-valor en un objeto de seguimiento.
Uso
// Sets a single field and value. ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs. ga('[trackerName.]set', fieldsObject);
Parámetros
En la referencia de campos puedes consultar la documentación de cada campo.
Devuelve
undefined
Ejemplos
// Sets the page field to "/about.html". ga('set', 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About". ga('set', { page: '/about.html', title: 'About' });
require
Requiere un complemento de analytics.js.
Uso
ga('[trackerName.]require', pluginName, [pluginOptions]);
Parámetros
Nombre | Tipo | Obligatorio | Descripción |
---|---|---|---|
pluginName |
string |
sí | Nombre del plugin que es obligatorio. Nota: Si no es un complemento oficial de analytics.js, se debe proporcionar en otro lugar de la página. |
pluginOptions |
Object |
No | Objeto de inicialización que se transmitirá al constructor del plugin después de crear la instancia. |
Devuelve
undefined
Ejemplo
// Requires the Enhanced Ecommerce plugin. ga('require', 'ec');
// Requires the Advertising Features plugin // named "myTracker" and override its default cookie name. ga('myTracker.require', 'displayfeatures', { cookieName: 'display_features_cookie' });
provide
Proporciona un complemento de analytics.js y sus métodos para usarlos con la cola de comandos ga()
.
ga('provide', pluginName, pluginConstuctor);
Parámetros
Nombre | Tipo | Obligatorio | Descripción |
---|---|---|---|
pluginName |
string |
sí | Nombre del plugin que se proporcionará. El nombre que se emplee debe ser el mismo que usen las llamadas a require. |
pluginConstuctor |
Function |
sí | Función de constructor que proporciona la lógica y los métodos del complemento. El constructor se invocará con el objeto pluginsOptions especificado en el método require. |
Ejemplo
// Defines a plugin constructor function MyPlugin(tracker, options) { // ... } // Provides the plugin for use with the ga() command queue. ga('provide', 'myplugin', MyPlugin);
remove
Retira un objeto de seguimiento.
Uso
ga('[trackerName.]remove');
Ejemplos
// Remove the default tracker. ga('remove');
// Remove the tracker named "myTracker". ga('myTracker.remove');