Plugins são scripts que melhoram a funcionalidade do analytics.js para ajudar a medir a interacção do utilizador. Os Plugins são tipicamente específicos para um conjunto de características que podem não ser requeridas por todos os utilizadores do Google Analytics, tais como o comércio electrónico ou medição de domínios cruzados, e por isso não estão incluídos no analytics.js por defeito.

Este guia explica como requerer e utilizar os plugins analíticos.js.

Requerendo plugins

O comando require toma o nome de um plugin e regista-o para utilização com o comando ga() fila de comandos. Se o plugin aceitar opções de configuração, essas opções podem ser passadas como argumento final para o comando require.

O seguinte é o completo require assinatura do comando:

ga('require', pluginName, );

Por exemplo, aqui está como seria necessário o plugin Enhanced Ecommerce para utilização com o rastreador padrão:

ga('require', 'ec');

E aqui está como exigiria o plugin de Características Publicitárias para um rastreador chamado “myTracker” e passar uma opção de configuração que substitui o valor padrão do nome do cookie:

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

Carregando o código do plugin

O comando require inicializa os métodos de plugin para utilização com o comando ga() fila de comandos, mas não carrega o script de plugin em si. Se estiver a utilizar um plugin de terceiros, ou a escrever você mesmo um plugin, terá de adicionar manualmente o código do plugin à página.

O método recomendado para adicionar o código do plugin à página é através de um <script> tag com o atributo async definido para assegurar que não bloqueia o carregamento de outras características no seu sítio.

O seguinte código requer e carrega um hipotético plugin de rastreamento de ligação:

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

A espera de plugins para carregar

Porque tanto a biblioteca analítica.js como a analítica.Os plugins js são carregados de forma assíncrona, pode ser um desafio saber quando os plugins estão completamente carregados e prontos para serem utilizados.

A biblioteca analytics.js resolve este problema ao parar a execução da fila de comandos quando encontra um comando require para um plugin que ainda não está carregado. Uma vez carregado o plugin, a execução da fila continua normalmente.

Como resultado, é extremamente importante que teste os plugins que está a utilizar para garantir que carregam e correm correctamente. Se um plugin não for carregado ou tiver um erro, impedirá que todos os subsequentes comandos analíticos.js executem.

Chamada de métodos plugin

Após a necessidade de um plugin, os seus métodos ficam disponíveis para utilização com o comando ga() fila de comandos. Aqui está a assinatura de comando para chamar os métodos plugin:

ga('methodName', ...args);

Por exemplo, o método addProduct do Ecommerce Enhanced Plugin’s addProduct pode ser chamado assim:

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

Or num tracker nomeado adicionando o nome do tracker à cadeia de comandos:

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

Se leu todos os guias nesta secção, deve estar familiarizado com a maioria das características da análise.js. O guia seguinte explica como depurar as suas implementações do analytics.js para detectar mais facilmente erros e ver exactamente o que o seu código está a fazer.