Os plug-ins são scripts que melhoram a funcionalidade da analytics.js para auxiliar na medição da interação do usuário. Normalmente, eles são específicos de um conjunto de recursos que podem não ser exigidos por todos os usuários do Google Analytics, como o de comércio eletrônico ou de avaliação de vários domínios, e não estão incluídos na analytics.js por padrão.
Neste guia, explicamos como exigir o uso dos plug-ins da analytics.js e como utilizá-los.
Plug-ins necessários
O comando require usa o nome de um plug-in e o registra para uso com a fila de comandos do ga(). Se o plug-in aceitar opções de configuração, elas poderão ser enviadas como o argumento final do 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 de publicidade para um rastreador chamado "myTracker" e transmitir uma opção de configuração que modifica 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 próprio script de plug-in. Se você está usando um plug-in de terceiros ou criando um novo, precisará adicionar manualmente o código à 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. Isso impede que o carregamento de outros recursos seja bloqueado no seu 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 o carregamento da biblioteca analytics.js e dos plug-ins dela ocorre de modo assíncrono, é difícil saber quando eles estão totalmente carregados e prontos para serem usados.
A analytics.js resolve esse problema interrompendo a execução da fila quando encontra um comando require para um plug-in que ainda não foi carregado. A execução da fila continua normalmente depois do carregamento completo do plug-in.
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 do 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. No próximo guia, explicamos como depurar as implementações da analytics.js para detectar erros com mais facilidade e ver exatamente a ação disparada pelo código.