Como criar plug-ins

Os plug-ins são scripts que melhoram a funcionalidade da analytics.js para auxiliar na solução de problemas e na avaliação da interação do usuário. Este guia descreve o processo de criação dos seus próprios plug-ins do analytics.js. Para ver informações sobre como usar os plug-ins do analytics.js nas suas próprias implementações, leia Uso de plug-ins.

Definição de um plug-in

Os plug-ins são definidos por meio do comando provide. Para chamar esse comando, é preciso usar o nome do plug-in como o primeiro argumento seguido pela função construtora. Quando o provide é executado, ele registra o plug-in que será usado com a fila de comandos do ga().

Construtor do plug-in

Veja a seguir o exemplo mais básico de plug-in da analytics.js:

// Defines the plugin constructor.
    function MyPlugin() {
      console.log('myplugin has been required...');
    }

    // Registers the plugin for use.
    ga('provide', 'myplugin', MyPlugin);
    

Os plug-ins precisam funcionar corretamente, mesmo nos casos em que o objeto ga global foi renomeado. Portanto, se você estiver criando um plug-in para uso de terceiros, inclua uma verificação que confirme se a variável GoogleAnalyticsObject foi definida como uma string diferente de 'ga'. Essa inspeção é feita pela função providePlugin a seguir:

// Provides a plugin name and constructor function to analytics.js. This
    // function works even if the site has customized the ga global identifier.
    function providePlugin(pluginName, pluginConstructor) {
      var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
      if (typeof ga == 'function') {
        ga('provide', pluginName, pluginConstructor);
      }
    }
    

Configuração de instâncias do plug-in

Quando a fila do ga() executa um comando require, ela instancia um novo objeto usando o operador new na função de construtor do plug-in provide. O construtor recebe o objeto do rastreador como seu primeiro argumento e todas as opções de configuração enviadas ao comando require como o segundo argumento.

Considere o seguinte comando require adicionado à tag do Google Analytics:

ga('create', 'UA-XXXXX-Y', 'auto');
    ga('require', 'localHitSender', {path: '/log', debug: true});
    ga('send', 'pageview');
    

E o código localHitSender:

function LocalHitSender(tracker, config) {
      this.path = config.path;
      this.debug = config.debug;
      if (this.debug) {
        console.log('localHitSender enabled for path: ' + this.path);
        console.log('on tracker: ' + tracker.get('name'));
      }
    }

    providePlugin('localHitSender', LocalHitSender);
    

Quando o comando require for executado, o seguinte resultado será registrado no console (o nome do rastreador padrão é "t0"):

// localHitSender enabled for path: /log
    // on tracker: t0
    

Definição de métodos do plug-in

Os plug-ins podem expor os próprios métodos que podem ser chamados usando a sintaxe da fila de comandos do ga:

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

em que trackerName é opcional e methodName corresponde ao nome de uma função no protótipo de construtores do plug-in. Se methodName não estiver presente no plug-in ou o próprio plug-in não existir, ocorrerá um erro.

Exemplo de chamadas de métodos do plug-in:

// Execute the 'doStuff' method using the 'myplugin' plugin.
    ga('create', 'UA-XXXXX-Y', 'auto');
    ga('require', 'myplugin');
    ga('myplugin:doStuff');

    // Execute the 'setEnabled' method of the 'hitCopy' plugin on tracker 't3'.
    ga('create', 'UA-XXXXX-Y', 'auto', {name: 't3'});
    ga('t3.require', 'hitcopy');
    ga('t3.hitcopy:setEnabled', false);
    

Exemplo de definições de métodos do plug-in:

// myplugin constructor.
    var MyPlugin = function(tracker) {
    };

    // myplugin:doStuff method definition.
    MyPlugin.prototype.doStuff = function() {
      alert('doStuff method called!');
    };

    // hitcopy plugin.
    var HitCopy = function(tracker) {
    };

    // hitcopy:setEnabled method definition.
    HitCopy.prototype.setEnabled = function(isEnabled) {
      this.isEnabled = isEnabled;
    }:
    

Carregamento de plug-ins

Os plug-ins normalmente são carregados a partir de um arquivo JavaScript diferente ou agrupados com seu código de aplicativo principal.

<script async src="myplugin.js"></script>
    

Os plug-ins não precisam necessariamente ser definidos antes de serem requeridos. Como a analytics.js e os plug-ins são carregados de forma assíncrona, a fila de comandos do ga() é criada para gerenciar esse processo.

Se a fila receber um comando require para um plug-in que ainda não foi fornecido, ela interromperá a execução dos itens restantes até que o plug-in esteja disponível.

O código a seguir mostra esse processo, em que o comando ga('require', 'myplugin') não é executado até que ga('provide', 'myplugin', ...) seja encontrado, três segundos depois.

ga('require', 'myplugin');

    function MyPlugin() {
      console.log('myplugin has been required...');
    }

    // Waits 3 second after running the `require`
    // command before running the `provide` command.
    setTimeout(function() {
      ga('provide', 'myplugin', MyPlugin);
    }, 3000);
    

Exemplos

O exemplo de plug-in a seguir captura valores de campanhas personalizados do URL de uma página e os passa ao rastreador. Esse plug-in demonstra como definir e registrar um script de plug-in, transmitir parâmetros de configuração do plug-in e definir e chamar os métodos do plug-in.

// campaign-loader.js

    function providePlugin(pluginName, pluginConstructor) {
      var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
      if (typeof ga == 'function') {
        ga('provide', pluginName, pluginConstructor);
      }
    }

    /**
     * Constructor for the campaignLoader plugin.
     */
    var CampaignLoader = function(tracker, config) {
      this.tracker = tracker;
      this.nameParam = config.nameParam || 'name';
      this.sourceParam = config.sourceParam || 'source';
      this.mediumParam = config.mediumParam || 'medium';
      this.isDebug = config.debug;
    };

    /**
     * Loads campaign fields from the URL and updates the tracker.
     */
    CampaignLoader.prototype.loadCampaignFields = function() {
      this.debugMessage('Loading custom campaign parameters');

      var nameValue = getUrlParam(this.nameParam);
      if (nameValue) {
        this.tracker.set('campaignName', nameValue);
        this.debugMessage('Loaded campaign name: ' + nameValue);
      }

      var sourceValue = getUrlParam(this.sourceParam);
      if (sourceValue) {
        this.tracker.set('campaignSource', sourceValue);
        this.debugMessage('Loaded campaign source: ' + sourceValue);
      }

      var mediumValue = getUrlParam(this.mediumParam);
      if (mediumValue) {
        this.tracker.set('campaignMedium', mediumValue);
        this.debugMessage('Loaded campaign medium: ' + mediumValue);
      }
    };

    /**
     * Enables / disables debug output.
     */
    CampaignLoader.prototype.setDebug = function(enabled) {
      this.isDebug = enabled;
    };

    /**
     * Displays a debug message in the console, if debugging is enabled.
     */
    CampaignLoader.prototype.debugMessage = function(message) {
      if (!this.isDebug) return;
      if (console) console.debug(message);
    };

    /**
     * Utility function to extract a URL parameter value.
     */
    function getUrlParam(param) {
      var match = document.location.search.match('(?:\\?|&)' + param + '=([^&#]*)');
      return (match && match.length == 2) ? decodeURIComponent(match[1]) : '';
    }

    // Register the plugin.
    providePlugin('campaignLoader', CampaignLoader);
    

O código acima pode ser incluído em uma página HTML assim:

<script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

    ga('create', 'UA-XXXXX-Y', 'auto');
    ga('require', 'campaignLoader', {
      debug: true,
      nameParam: 'cname',
      sourceParam: 'csrc',
      mediumParam: 'cmed'
    });
    ga('campaignLoader:loadCampaignFields');

    ga('send', 'pageview');
    </script>

    <!--Note: plugin scripts must be included after the tracking snippet. -->
    <script async src="campaign-loader.js"></script>
    

Plug-ins do AutoTrack

A biblioteca do AutoTrack é de código aberto, está disponível no GitHub e inclui vários plug-ins da analytics.js que auxiliam no acompanhamento de interações comuns do usuário. Consulte o código-fonte do AutoTrack para entender melhor o funcionamento dos plug-ins.