Referencia de la cola de comandos ga

La cola de comandos de ga() proporciona una interfaz para hacer casi todo lo que necesitas hacer con la biblioteca analytics.js.

El fragmento de seguimiento de JavaScript define la función inicial de la cola de comandos ga(), de modo que se pueda usar incluso antes de que la biblioteca analytics.js se cargue por completo. Cuando se carga la biblioteca analytics.js, los elementos de la cola de comandos se ejecutan en el orden en que se recibieron. Una vez hecho esto, los comandos nuevos que se envían a la cola se ejecutan de inmediato.

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 muchos formatos diferentes. En este documento, se detallan todas las formas en las que se puede invocar la función de cola de comandos de ga().

Firma de la función
ga(command, [...fields], [fieldsObject])

Invocar la función de cola de comandos ga() con la siguiente firma de función enviará los comandos a la cola para que se programen para su ejecución una vez que se cargue la biblioteca.
ga(readyCallback)

Si invocas la función de cola de comandos ga() pasando una función, se programará la función que se pasó para que se ejecute en el siguiente punto de la cola.

Dado que los comandos solo se ejecutan después de que la biblioteca analytics.js está completamente cargada, el motivo más común para pasar una función a la cola de comandos es como una devolución de llamada para cuando la biblioteca analytics.js se carga y está lista.

Agrega comandos a la cola

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

Uso

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

Parámetros

Nombre Tipo Obligatorio Descripción
command string sí

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

[trackerName.][pluginName:]methodName
trackerName El nombre de la herramienta de seguimiento en la que se invocará el comando programado. Si no se especifica ningún nombre de dispositivo de rastreo, se invoca el comando en el dispositivo de seguimiento predeterminado.
pluginName Es el nombre de un complemento analytics.js obligatorio. Si se especifica pluginName, methodName debe ser un método proporcionado por el complemento.
methodName El nombre del método que se programará para la ejecución. Cuando no se especifica el nombre de un complemento, este método debe ser uno de los métodos de comando que se indican a continuación.
...fields * no Uno o más parámetros de conveniencia opcionales para especificar campos comunes con rapidez. La cantidad de campos específicos y permitidos varía según el método de comando al que se llame.
fieldsObject Object no

Es un objeto para especificar los valores restantes que no se especificaron en ninguno de los parámetros de fields.

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

Consulta la referencia de campos para ver la documentación de campos individuales.

Ejemplos

Consulta la sección de métodos de comando a continuación para ver ejemplos de comandos individuales.

Listo para devolución de llamada

Si invocas la función de cola de comandos ga() pasando una función, se programará la función que se pasó para que se ejecute en el siguiente punto de la cola.

Dado que los comandos solo se ejecutan después de que la biblioteca analytics.js está completamente cargada, el motivo más común para pasar una función a la cola de comandos es como una devolución de llamada para cuando la biblioteca analytics.js se carga y está lista.

Uso

ga(readyCallback)

Parámetros

Nombre Tipo Obligatorio Descripción
readyCallback Function sí

Una función de devolución de llamada que se invocará cuando la biblioteca esté completamente cargada y lista para que se pueda interactuar con ella La función se invoca con el objeto de seguimiento predeterminado como primer argumento. Si no se creó un rastreador predeterminado, el primer argumento es undefined.

Nota: Cuando se invoca la función de devolución de llamada, se pueden usar 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 del método de comando

La siguiente es una lista de todos los métodos que se pueden pasar a la cola de comandos de ga() (excepto los métodos de complementos).

create

Crea una instancia de seguimiento nueva con los campos especificados.

Uso

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

Parámetros

Consulta la referencia de campos para ver la documentación de campos individuales.

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 fieldsObject, combinados con los campos almacenados actualmente en la herramienta de seguimiento.

Parámetros

Los campos que se pueden especificar con los parámetros de ...fields varían según el tipo de hit. En la siguiente tabla, se incluyen los campos que corresponden a cada tipo de hit. Los tipos de hits que no figuran en la lista no aceptan parámetros ...fields, solo fieldsObject.

Tipo de hit ...fields
pageview page
event eventCategory, eventAction, eventLabel, eventValue
social socialNetwork, socialAction, socialTarget
timing timingCategory, timingVar, timingValue, timingLabel

Consulta la referencia de campos para ver la documentación de campos individuales.

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

Establece 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

Consulta la referencia de campos para ver la documentación de campos individuales.

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í El nombre del complemento que se requerirá. Nota: Si el complemento no es un complemento oficial de analytics.js, se debe proporcionar en otra parte de la página.
pluginOptions Object no Un objeto de inicialización que se pasará al constructor del complemento cuando se cree 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 analytics.js y sus métodos para usar con la cola de comandos de ga().

ga('provide', pluginName, pluginConstuctor);

Parámetros

Nombre Tipo Obligatorio Descripción
pluginName string sí Es el nombre del complemento que se proporciona. El nombre que se use debe ser el mismo que usa cualquier llamada de require.
pluginConstuctor Function sí Una función de constructor que proporciona toda la lógica y los métodos del complemento Este 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

Quita un objeto de seguimiento.

Uso

ga('[trackerName.]remove');

Ejemplos

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

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