Referencia de la cola de comandos ga

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.

Nota: Los fragmentos de seguimiento JavaScript permiten cambiar el nombre de la función de la cola de comandos ga(). Si lo haces, asegúrate de que el código que copies de este sitio haga referencia al nombre nuevo.

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() 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.
ga(readyCallback)	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.

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 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 del complemento de analytics.js que se ha solicitado. Si se ha especificado pluginName, el valor de methodName debe ser un método que proporcione el complemento. methodName Nombre del método que está programado para ejecutarse. Si no se especifica un nombre de complemento, este método debe ser uno de los métodos de comando que se indican 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 al 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.

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 undefined. Nota: Cuando se invoca la función de retrollamada, pueden usarse todos los métodos del objeto ga.

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'
});

Importante: No se puede especificar un nombre de objeto de seguimiento en la parte de método de la llamada de creación. Por ejemplo, ga('myTracker.create', 'UA-XXXXX-Y`) no funciona.

Para obtener más información, consulta la guía Crear objetos de seguimiento.

---

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.

Nota: Los valores especificados en ...fields y en fieldsObject se envían con un hit concreto, pero no se almacenan en el objeto de seguimiento. Para modificar el objeto de seguimiento, usa el método set.

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
});

Si quieres obtener más información sobre cómo enviar hits, consulta la guía Enviar datos a Google Analytics.

---

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'
});

Si quieres más información acerca de cómo modificar los objetos de seguimiento, consulta la guía Obtener y definir datos del objeto de seguimiento.

---

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'
});

Si quieres obtener más información acerca de cómo solicitar complementos de analytics.js, consulta la guía Usar complementos.

---

provide

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

ga('provide', pluginName, pluginConstuctor);

Nota: A diferencia de la mayoría de los métodos de la cola ga(), "provide" no acepta un nombre de objeto de seguimiento.

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);

Si quieres obtener más información acerca de cómo proporcionar complementos de analytics.js, consulta la guía Crear complementos.

---

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');