Referencia de la cola de comandos de ga

La cola de comandos de 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 de ga(), por lo que se puede usar incluso antes de que la biblioteca analytics.js se cargue por completo. Tan pronto como 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])

Invocar la función de cola de comandos de ga() con la siguiente firma de función enviará los comandos a la cola para programar su ejecución cuando se cargue la biblioteca.

ga(readyCallback)

Invocar la función de cola de comandos de ga() pasándole una función programará la ejecución de la función pasada 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 pasar una función a la cola de comandos es usarla como devolución de llamada cuando la biblioteca analytics.js esté cargada y preparada.

Agregar comandos a la cola

Invocar la función de cola de comandos de ga() con la siguiente firma de función enviará los comandos a la cola para programar su ejecución cuando se cargue la biblioteca.

Uso

ga(command, [...fields], [fieldsObject])

Parámetros

Nombre Tipo Obligatorio Descripción
command string

Identificador que representa el comando que se agregará a la cola. El identificador se compone de tres partes (las dos primeras son opcionales):

[trackerName.][pluginName:]methodName
trackerName Nombre del objeto de seguimiento en el que se invocará el comando programado. Si no se especifica ningún nombre de objeto de seguimiento, el comando se invoca en el objeto predeterminado.
pluginName Nombre de un plugin de analytics.js que se ha solicitado. Si se ha especificado pluginName, el valor de methodName debe ser un método que proporcione el plugin.
methodName Nombre del método que está programado para ejecutarse. Si no se especifica un nombre de plugin, este método debe ser uno de los métodos de comando enumerados más adelante.
...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 que se llame.
fieldsObject Object no

Objeto para especificar los valores restantes que no se indican en ninguno de los parámetros de fields.

Si se configura un campo en el parámetro fields y fieldsObject, se usará el valor de fieldsObject.

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.

Devolución de llamada de proceso preparado

Invocar la función de cola de comandos de ga() pasándole una función programará la ejecución de la función pasada 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 pasar una función a la cola de comandos es usarla como devolución de llamada cuando la biblioteca analytics.js esté cargada y preparada.

Uso

ga(readyCallback)

Parámetros

Nombre Tipo Obligatorio Descripción
readyCallback Function

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 undefined.

Nota: Cuando se invoca la función de devolución de llamada, todos los métodos de objeto de ga están disponibles para usarse.

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 ofrece una lista de todos los métodos que se pueden pasar a la cola de comandos de ga(), excepto los métodos de plugin.

create

Permite crear una nueva 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

Permite enviar 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 actualmente 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. Si algún tipo no se incluye en la lista, significa que no acepta 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 plugin de analytics.js.

Uso

ga('[trackerName.]require', pluginName, [pluginOptions]);

Parámetros

Nombre Tipo Obligatorio Descripción
pluginName string Nombre del plugin que es obligatorio. Nota: Si no es un complemento oficial de analytics.js, se debe proporcionar en otra parte de la página.
pluginOptions Object no Objeto de inicialización que se pasará al constructor del plugin después de crear la instancia.

Devuelve

undefined

Ejemplo

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Display Features plugin for the tracker
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

Proporciona un plugin de analytics.js y sus métodos para usarlos con la cola de comandos de ga().

ga('provide', pluginName, pluginConstuctor);

Parámetros

Nombre Tipo Obligatorio Descripción
pluginName string Nombre del plugin que se proporcionará. El nombre que se emplee debe ser el mismo que usan las llamadas a require.
pluginConstuctor Function Función de constructor que proporciona la lógica y los métodos del plugin. 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

Elimina un objeto de seguimiento.

Uso

ga('[trackerName.]remove');

Ejemplos

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');