Uso de plug-ins

Os plug-ins são scripts que melhoram a funcionalidade do analytics.js para auxiliar na avaliação da interação com o usuário. Os plug-ins normalmente são específicos de um conjunto de recursos que não são obrigatórios para todos os usuários do Google Analytics, como comércio eletrônico ou acompanhamento de vários domínios. Portanto, eles não são incluídos no analytics.js por padrão.

Este guia explica como requerer e usar plug-ins do analytics.js.

Requisição de plug-ins

O comando require registra o nome de um plug-in para uso com a fila de comandos do ga(). Se o plug-in aceita opções de configuração, elas podem ser transmitidas como o argumento final ao comando require.

Veja a seguir a assinatura completa do comando require:

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

Por exemplo, veja como requerer o plug-in de comércio eletrônico avançado para uso com o rastreador padrão:

ga('require', 'ec');

Agora veja como requerer o plug-in de recursos da Rede de Display para um rastreador chamado "myTracker" e transmitir uma opção de configuração que substitui o valor do nome do cookie padrão:

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

Carregamento do código do plug-in

O comando require inicializa os métodos do plug-in para uso com a fila de comandos do ga(), mas não carrega o script do plug-in propriamente dito. Se você está usando um plug-in de terceiros ou criando um plug-in, precisará adicionar manualmente o código do plug-in à página.

O método recomendado para adicionar o código do plug-in à página é por meio de uma tag <script> com o atributo async definido para garantir que ele não bloqueie o carregamento de outros recursos no site.

O código a seguir requer e carrega um plug-in hipotético de acompanhamento de links:

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

Aguardar o carregamento dos plug-ins

Como a biblioteca do analytics.js e os plug-ins do analytics.js são carregados de modo assíncrono, é difícil saber quando os plug-ins estão totalmente carregados e prontos para serem usados.

A biblioteca do analytics.js resolve esse problema interrompendo a execução da fila de comandos quando encontra um comando require para um plug-in que ainda não está carregado. Depois que o plug-in é carregado, a execução da fila continua normalmente.

Assim, é extremamente importante que você teste os plug-ins usados para garantir que eles sejam carregados e executados corretamente. Se um plug-in não for carregado ou tiver um erro, ele impedirá que todos os comandos subsequentes do analytics.js sejam executados.

Chamada de métodos do plug-in

Após a requisição de um plug-in, os métodos dele são disponibilizados para uso com a fila de comandos do ga(). Veja a seguir a assinatura do comando para chamar métodos do plug-in:

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

Por exemplo, o método addProduct do plug-in de comércio eletrônico avançado pode ser chamado assim:

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

Ele também pode ser chamado em um rastreador nomeado por meio da adição do nome do rastreador à string de comando:

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

Próximas etapas

Se você leu todos os guias desta seção, conhece a maioria dos recursos do analytics.js. O próximo guia explica como depurar as implementações do analytics.js para detectar erros com mais facilidade e ver exatamente o que o código está fazendo.