Acompanhamento de gadgets

Este documento descreve como usar a nova API de gadget para acompanhamento de gadgets do Google Analytics. Essa API oferece um modelo de dados aprimorado e acompanhamento de desempenho para coletar estatísticas de relatórios do Google Analytics dos seus gadgets.

  1. Antes de começar
  2. Rastrear seu gadget
  3. Métodos de acompanhamento
  4. Considerações sobre o uso
  5. Dicas
 

Antes de começar

No Google Analytics, cada domínio ou subdomínio de website único que você adicionar à sua conta é acompanhado em uma vista da propriedade (perfil) diferente e recebe um ID de domínio diferente. Como cada gadget funciona no próprio subdomínio no site do host gmodules.com, convém acompanhar cada gadget que você criar na própria vista da propriedade (perfil) e com um ID de domínio exclusivo.

A maneira mais simples de fazer isso é deixar que o Google Analytics gere um ID exclusivo para você.

  1. Para começar, faça login no Google Analytics ou inscreva-se em uma conta do Google Analytics.
    • Novos usuários verão a página Inscrição para uma nova conta.
    • Os usuários existentes devem acessar a página Configurações do Google Analytics e clique em Adicionar vista da propriedade do website (perfil). Escolha novo domínio.
  2. Em qualquer uma dessas páginas, insira o URL de qualquer website válido.
    3. Como o URL do site é apenas uma string que o software Google Analytics vincula ao seu ID de domínio, esse URL pode ser qualquer string de URL de site válido, seja ela fictícia ou real. Você não instalará o código de acompanhamento em nenhuma página da Web nem precisará de acesso a nenhuma página do website.
  3. Clique no botão para passar à próxima tela.
    4. Quando o snippet de código de acompanhamento aparecer, copie o ID de domínio exclusivo em um bloco de rascunho. O snippet de código gerado automaticamente contém esse ID de domínio no formato UA-123456-1.
  4. Clique no botão Finish.
    5. O nome do URL do seu site vai aparecer na lista da vista (perfil). Você também pode alterar o nome da vista da propriedade (perfil) para algo mais significativo. Para isso, clique no link Editar dela e, depois, em Editar novamente.
  5. Use o ID de domínio gerado no código de acompanhamento do gadget.
    6. Os IDs de domínio do Google Analytics têm o seguinte formato:
    UA-123456-1
 

Acompanhamento do seu gadget

O processo de acompanhamento do gadget envolve três inclusões no código dele:

  1. Ativação do recurso.
  2. Criação de um objeto de acompanhamento.
  3. Acompanhamento do gadget por meio de um método escolhido entre dois métodos.

O exemplo de código de gadget a seguir mostra cada uma dessas inclusões no código, que são explicadas abaixo. Você pode usar este arquivo de exemplo para iniciar seu próprio gadget.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Analytics Test">
     <!-- Sets the feature -->
     <Require feature="com.google.gadgets.analytics" /> 
     <Require feature="setprefs" /> 
  </ModulePrefs>
  <UserPref 
      name="counter"
      datatype="hidden"
      default_value="0" />
  <Content type="html"> 
  <![CDATA[ 
      <script>
      // Track this gadget using Google Analytics.

      // Creates a tracking object and uses reportPageview method to call gadget view
      var ga = new _IG_GA("UA-00000-1");
      ga.reportPageview('/view/counterGadget');

      // Suppose, for example, you have a gadget with two counter buttons.
      // You can track interactions with those counters via Analytics.

      // Increment value of "counter" user preference
      function incrementCounter() {
         var count = prefs.getInt("counter");

         prefs.set("counter", count + 1);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Increment", "Button", 0);
      }

      // Reset value of "counter" userpref to 0
      function resetCounter(){
         prefs.set("counter", 0);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Reset", "Button", 0);
      }
      </script>
      <form name="counter">
      <input type=button value="Reset" name="reset" onClick="resetCounter()">
      <input type=button value="Count" name="count" onClick="incrementCounter()">
      </form>
  ]]>
  </Content>
</Module>

1. Ativação do recurso

Primeiro, ative o recurso importando a biblioteca do Google Analytics por meio do namespace do recurso:

 <Require feature="com.google.gadgets.analytics" />

2. Criação de um objeto de acompanhamento

A API de acompanhamento do Google Analytics está em conformidade com o mesmo modelo orientado a objetos do código de acompanhamento ga.js. Portanto, antes de acompanhar seu gadget, crie uma instância de um objeto de acompanhamento:

var ga = new _IG_GA("UA-123456-1");

É nela que você inserirá o ID de domínio gerado seguindo as etapas acima.

É necessário usar o ID de domínio completo com o número final único. Caso contrário, haverá falha na chamada do objeto de acompanhamento.

3. Acompanhamento do seu gadget

A API de gadgets fornece dois métodos que você pode usar para acompanhar interações nos seus gadgets:

  • Método de URL virtual
    • ga.reportPageview(path);

    Esse método acompanha estatísticas de gadgets como exibições de página especiais e é o mesmo método usado na versão anterior da API de gadgets do Google Analytics. Ao usar esse método, você pode atualizar qualquer código de acompanhamento de gadgets pré-existente sem afetar o layout dos seus relatórios existentes do Google Analytics. Você visualiza dados de relatórios nos gadgets da mesma maneira que os visualiza para páginas da Web.

    Quando você usa o método de URL virtual para acompanhar interações de gadgets, cada chamada é registrada como uma solicitação de página para a string fornecida como um parâmetro ao método. Você pode aproveitar esse comportamento para transmitir um caminho de URL fabricado para que possa visualizar relatórios de gadgets na interface do Google Analytics da mesma forma como visualizaria relatórios de páginas de websites. Por exemplo, você pode usar caminhos diferentes para acompanhar vistas da propriedade e interações de gadgets: 

    ga.reportPageview('/view/counterGadget');
ga.reportPageview('/click/increment');
ga.reportPageview('/click/reset');

  • Método de acompanhamento de eventos
    • ga.reportEvent(name, action, [[]label], [[]value]);

    Esse método está disponível somente na nova API de gadgets do Google Analytics. Com esse método, você pode acompanhar exibições de página (por exemplo, renderização de gadgets) separadamente das interações dos usuários no seu gadget.

    Observação: No momento, o acompanhamento de eventos está na versão Beta fechada. Use o método de URL virtual se você não tiver acesso ao acompanhamento de eventos.

    O método do evento fornece outro modelo para você usar com o acompanhamento de gadgets. Em primeiro lugar, as chamadas de eventos são calculadas separadamente das chamadas de exibições de página, e os dados resultantes são exibidos em outra parte dos Relatórios de conteúdo do Google Analytics. Desse modo, você poderá acompanhar a Vista de um gadget separadamente das interações dos usuários no gadget sem que elas aumentem o número geral de Vistas do gadget. Em segundo lugar, esse método utiliza o modelo de acompanhamento de eventos, cuja estrutura é projetada especificamente para analisar as interações dos usuários nos gadgets. Nesse modelo, o rótulo e o valor são parâmetros opcionais.

    Tomando o exemplo dos contadores, podemos usar o método de eventos para acompanhar quais funções dos gadgets são acionadas e transmitir o tipo de controle, que é um botão em ambos os casos. 

    ga.reportEvent("Counter Gadget", "Increment", "Button");
ga.reportEvent("Counter Gadget", "Reset", "Button");

    Esse exemplo é muito simples, mas o modelo de acompanhamento de eventos é uma estrutura altamente flexível que você pode refinar para tirar proveito dos requisitos de acompanhamento exclusivos do seu gadget. Para mais informações, consulte a documentação sobre acompanhamento de eventos.

 

Métodos de acompanhamento

No momento, o recurso do Google Analytics oferece os métodos a seguir. O uso deles é discutido acima.

  • reportPageview()
    • Requer uma string para preencher corretamente os relatórios de conteúdo. Normalmente, essa string tem a forma de um caminho que você define para fins de relatórios. O valor transmitido a esse método é enviado na solicitação GIF pela variável utmp. Use esse método para acompanhar as cargas e as interações do gadget. 
    ga.reportPageview("/view/gadgetName");
    parameters
    String  path Caminho a ser fornecido para o URL virtual desse elemento.

  • reportEvent()
    • Exige o nome do gadget e o parâmetro de ação para inserir corretamente os dados rastreados nos relatórios de acompanhamento de eventos. Os outros parâmetros são opcionais. Os valores transmitidos por esse método são enviados na visualização da solicitação GIF na variável utme.

    parameters
    String  name  Obrigatório.Uma string usada no nível superior dos relatórios do acompanhamento de eventos. Por exemplo, se você acompanhar interações em diversos elementos de gadget, provavelmente usará o próprio nome do gadget nesse parâmetro para que todo o acompanhamento de interações do gadget seja agregado na mesma seção que os relatórios do Google Analytics.

    String  action  Obrigatório. String para segmentar ainda mais a interação com o gadget nos Relatórios do Acompanhamento de eventos. Para mais informações, consulte a documentação sobre acompanhamento de eventos.

    String  label  Opcional. String que você pode usar como um segmento secundário para seu gadget.

    Int  value  Opcional. Número que você pode fornecer como um valor para a interação com o gadget. Esse número é agregado sempre que o método é invocado.

 

Considerações de uso

A API de gadgets do Google Analytics possui diversas considerações de uso:

  • Contêineres compatíveis
    • Muitos tipos de contêineres são compatíveis com a API de gadgets do Google Analytics, incluindo, mas não se limitando a:
    • iGoogle
    • Open Syndication
    • Open Social
    • Gadgets
  • Tipos de gadget não compatíveis
    • A API de gadgets do Google Analytics não é compatível com os tipos de gadget a seguir:
    • Gadgets inline (type=html-inline)
    • Mapplets
    • Gadgets do tipo URL (type-url)
    • Anúncios de gadgets no Google AdSense
  • Considerações sobre domínios
    • Quando você precisa do recurso do Google Analytics para seu gadget, ele é redirecionado para <subdomain>.gmodules.com, em que <subdomain> é um subdomínio aleatório exclusivo. Por isso, todo o conteúdo do gadget é exibido nesse subdomínio. Exemplo: 3nvma227-a.gmodules.com. Além disso, todos os cookies de acompanhamento do Google Analytics são definidos para esse subdomínio exclusivo. Por esse motivo, os mapplets não são suportados pelo recurso de acompanhamento do Google Analytics. Além disso, você precisa permitir especificamente que o conteúdo em Flash tenha acesso especial ao recurso de acompanhamento (veja abaixo).
  • Widgets que usam conteúdo em Flash
    • Os gadgets que usam conteúdo em Flash precisam ativar especificamente a comunicação entre o URL do Flash e o URL dos gadgets definindo o parâmetro allowScriptAccess como "sempre". 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

Dicas

A melhor maneira de usar o método de URL virtual

Se você não tem acesso ao método de acompanhamento de eventos para seus gadgets, siga estas recomendações para acompanhar seus gadgets com o método de URL virtual:

  • Segmente a carga do seu gadget de maneira diferente.
    • Você pode chamar o ga.reportPageview() na carga do gadget, informando um caminho que segmenta as estatísticas de carga/visualização do gadget separadamente das métricas de interação com o gadget. Isso manterá os dados de relatórios de conteúdo do gadget em um "diretório" diferente das interações com o gadget de modo que você possa ver suas Vistas gerais separadamente do número de interações com o gadget em si. Por exemplo, o snippet de código a seguir pode ser usado no seu gadget para exibir todas as estatísticas de carga dele: 
      ga.reportPageview('/view/gadgetName');
  • Segmente diferentes tipos de interação entre si.
    • Chame a ga.reportPageview() com um caminho que segmente diferentes interações do usuário. Desse modo, você pode gerar relatórios de conteúdo diferentes para links de gadgets, botões de gadgets ou outros widgets cujos dados de interação convém acompanhar. Por exemplo:
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

Uso do método de acompanhamento de eventos

Se você tem acesso ao recurso de acompanhamento de eventos nos relatórios do Google Analytics, use o modelo de dados altamente flexível para aproveitar ao máximo o acompanhamento dos seus objetos. Veja algumas dicas:

  • Acompanhe a impressão ou a visualização do gadget com o ga.reportPageview() e a interação com o gadget com ga.reportEvent().
    • As visualizações de gadget são exibidas na seção "Conteúdo" dos dados da página, e as interações com o gadget aparecem na seção "Eventos" dos relatórios de conteúdo.
  • Use document.referrer como parâmetro para saber onde seu gadget foi colocado.
    • No gadget, document.referrer geralmente é o URL da página do contêiner. Assim, você pode transmiti-lo como um parâmetro de rótulo no método ga.reportEvent():
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Solução de problemas

Use ferramentas de terceiros para analisar a string de solicitação GIF do seu gadget com a finalidade de verificar se os dados serão enviados aos relatórios do Google Analytics da maneira que você espera. Quando o gadget estiver devidamente hospedado e funcionando na sua página de teste, analise a string da solicitação GIF assim:

  • Método de exibição de página
    • Procure a variável utmp nos parâmetros da solicitação GIF. As informações associadas a essa variável são as que serão enviadas aos relatórios do Google Analytics como o "caminho" do gadget.
  • Método de Acompanhamento de eventos
    • Procure a variável utme nos parâmetros da solicitação GIF. Essas informações precisam estar no formato 5(object*action*label)(value).

Para mais informações sobre como solucionar problemas do código de acompanhamento, consulte o Guia de solução de problemas do GATC.