Os plug-ins são scripts que melhoram a funcionalidade da analytics.js para ajudar a medir a interação com o 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.