Usar complementos

Los complementos son secuencias de comandos que mejoran la funcionalidad de analytics.js para medir la interacción del usuario. Por lo general, los complementos son específicos de un conjunto de funciones, como el comercio electrónico o el seguimiento multidominio, que es posible que no necesiten todos los usuarios de Google Analytics y, por lo tanto, no están incluidos 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 toma el nombre de un complemento y lo registra para su uso con la cola de comandos de ga(). Si el complemento acepta opciones de configuración, se pueden pasar como el 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');

Y el modo de solicitar el complemento de las funciones de display en el objeto de seguimiento "myTracker" y pasarle 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 agregar manualmente el código del complemento a la página.

El método recomendado para agregar el código del complemento a la página es hacerlo a través de la etiqueta <script> con el atributo async configurado para garantizar que no bloquea la carga de otras funciones de tu 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 del modo 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 del siguiente modo:

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

O en un objeto de seguimiento con nombre se puede agregar el nombre de dicho objeto a la cadena de comando:

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

Pasos siguientes

Si has leído todas las guías de esta sección, debes estar familiarizado con la mayoría de funciones de analytics.js. En la siguiente 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.