Usar complementos

Los complementos son secuencias de comandos que mejoran la funcionalidad de analytics.js para medir las interacciones de los usuarios. Suelen ser específicos de un conjunto de funciones que no son necesarias para todos los usuarios de Google Analytics, como el comercio electrónico o la medición multidominio, por lo que no se incluyen en analytics.js de forma predeterminada.

En esta guía se explica cómo solicitar y usar los complementos de analytics.js.

Solicitar complementos

El comando require usa el nombre de un complemento y lo registra en la cola de comandos de ga(). Si el complemento acepta opciones de configuración, estas opciones se pueden transferir como argumento final del comando require.

A continuación se muestra la firma completa del comando require:

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

Por ejemplo, el modo de solicitar el complemento de comercio electrónico mejorado para usarlo con el objeto de seguimiento predeterminado es el siguiente:

ga('require', 'ec');

El modo de solicitar el complemento de funciones publicitarias en el objeto de seguimiento "myTracker" y transmitir una opción de configuración que anule el valor de nombre de cookie predeterminado es el siguiente:

ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

Cargar el código del complemento

El comando require inicializa los métodos del complemento para usarlos con la cola de comandos de ga(), pero no carga la secuencia de comandos del complemento. Si utilizas un complemento de terceros o escribes uno, tendrás que añadir manualmente el código del complemento a la página.

El método recomendado para añadir código del complemento a la página es mediante una etiqueta <script> con el atributo async especificado de tal forma que no bloquee la carga de otras funciones del sitio web.

En el código siguiente se requiere y se carga un hipotético complemento de seguimiento de enlaces:

<script>
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'linkTracker');
ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="/path/to/link-tracker-plugin.js"></script>

Esperar a que se carguen los complementos

Como la biblioteca analytics.js y sus complementos se cargan de forma asíncrona, puede ser difícil saber cuándo los complementos están totalmente cargados y listos para usarse.

La biblioteca analytics.js soluciona este problema deteniendo la ejecución de la cola de comandos cuando encuentra un comando require correspondiente a un complemento que todavía no está cargado. Una vez que se carga el complemento, la ejecución de la cola continúa de forma normal.

Por lo tanto, es fundamental que pruebes los complementos que usas para garantizar que se cargan y ejecutan correctamente. Si un complemento no se carga o tiene un error, se impedirá la ejecución de los comandos de analytics.js posteriores.

Llamar a los métodos del complemento

Después de solicitar un complemento, sus métodos se pueden usar con la cola de comandos de ga(). La firma de comando para llamar a los métodos del complemento es la siguiente:

ga('[trackerName.][pluginName:]methodName', ...args);

Por ejemplo, el método addProduct del complemento de comercio electrónico mejorado se puede llamar de la siguiente forma:

ga('ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

En un objeto de seguimiento con nombre, se puede añadir el nombre de dicho objeto a la cadena de comandos:

ga('myTracker.ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

Pasos siguientes

Si has leído todas las guías de esta sección, te habrás familiarizado con la mayoría de las funciones de analytics.js. En la siguiente guía se explica cómo depurar las implementaciones de analytics.js para detectar más fácilmente los errores y comprobar exactamente lo que hace el código.