SDK do Google Analytics para Android v1 (legada)

O SDK de aplicativos para dispositivos móveis do Google Analytics para Android facilita a implementação do Google Analytics em aplicativos baseados em Android. Este documento descreve como integrar o SDK aos seus apps.

Visão geral do SDK

Esse SDK usa um modelo de acompanhamento projetado para acompanhar os usuários em sites tradicionais e na interação com widgets em páginas da Web tradicionais. Por esse motivo, os termos usados abaixo refletem o modelo de acompanhamento convencional de sites e estão sendo associados ao acompanhamento de aplicativos para dispositivos móveis. Você precisa estar familiarizado com o acompanhamento do Analytics para entender como esse SDK funciona.

Use o SDK de acompanhamento para dispositivos móveis e acompanhe seus aplicativos para telefone com os seguintes tipos de interação do Google Analytics:

Acompanhamento de visualização de página
Uma visualização de página é um meio padrão para medir o volume de tráfego de um site tradicional. Como apps para dispositivos móveis não contêm páginas HTML, você precisa decidir quando e com que frequência acionar uma solicitação de visualização de página. Além disso, como as solicitações de visualização de página foram criadas para gerar relatórios sobre estruturas de diretórios, dê nomes descritivos às solicitações para aproveitar a nomenclatura do caminho da página nos relatórios de conteúdo do Google Analytics. Os nomes escolhidos são preenchidos nos relatórios do Google Analytics como caminhos de página, embora não sejam, na verdade, páginas HTML. No entanto, você pode usar isso a seu favor estruturando caminhos para fornecer mais agrupamentos às chamadas.
Acompanhamento de eventos
No Google Analytics, os eventos são projetados para acompanhar a interação do usuário com elementos da página da Web de maneira diferente das solicitações de visualização de página. Você pode usar o recurso Acompanhamento de eventos do Google Analytics para fazer chamadas adicionais que serão informadas na seção Acompanhamento de eventos da interface de relatórios do Analytics. Os eventos são agrupados em categorias e também podem usar rótulos por evento, o que oferece flexibilidade na geração de relatórios. Por exemplo, um app multimídia pode ter ações play/stop/pause para a categoria video e atribuir um rótulo para cada nome de vídeo. Os relatórios do Google Analytics agregariam eventos de todos os eventos marcados com a categoria vídeo. Para mais informações sobre o acompanhamento de eventos, consulte o Guia de acompanhamento de eventos
Acompanhamento de comércio eletrônico
Use o recurso de acompanhamento de e-commerce para acompanhar transações do carrinho de compras e compras no aplicativo. Para acompanhar uma transação, use a classe Transaction para representar as informações gerais da compra, e a classe Item para representar cada produto no carrinho de compras. Depois de coletados, os dados podem ser visualizados na seção "Relatórios de e-commerce" da interface do Google Analytics. Para mais informações sobre o acompanhamento de comércio eletrônico, consulte o Guia de acompanhamento de comércio eletrônico.
Variáveis personalizadas
As variáveis personalizadas são tags com pares de nome-valor que podem ser inseridas no código de acompanhamento para refinar o acompanhamento do Google Analytics. Para mais informações sobre como usar variáveis personalizadas, leia o Guia de variáveis personalizadas.

Como começar

Requisitos

Para integrar os recursos de acompanhamento do Google Analytics ao seu app Android, você precisará do seguinte:

Configuração

  • Adicione libGoogleAnalytics.jar ao diretório /libs do projeto.
  • Adicione as seguintes permissões ao arquivo de manifesto AndroidManifest.xml do seu projeto:
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

O SDK inclui um aplicativo de exemplo que demonstra como o projeto deve ficar se tiver sido configurado corretamente. Você pode usá-lo como modelo para seus próprios aplicativos integrados ao Google Analytics.

Como usar o SDK

Antes de começar a usar o SDK, é necessário criar uma conta sem custo financeiro em www.google.com.br/analytics e criar uma nova propriedade da Web nessa conta usando um URL falso, mas descritivo do site (por exemplo, http://mymobileapp.mywebsite.com). Depois de criar a propriedade, anote ou mantenha uma cópia do ID da propriedade da Web gerado para a propriedade recém-criada.

Você precisa indicar aos usuários, no próprio aplicativo ou nos Termos de Serviço, que você se reserva o direito de acompanhar e relatar anonimamente a atividade de um usuário dentro do app. O uso do SDK do Google Analytics também é regido pelos Termos de Serviço do Google Analytics, com os quais você precisa concordar ao criar uma conta.

Amostras e práticas recomendadas

Você pode encontrar exemplos de código e práticas recomendadas em code.google.com, no projeto analytics-api-samples.

Biblioteca EasyTracker

Uma biblioteca do EasyTracker está disponível. Ele oferece rastreamento dos aplicativos e da atividade quase sem esforço de desenvolvimento. Você pode encontrá-lo na seção Downloads do projeto analytics-api-samples.

Iniciando o tracker

Para receber o Singleton do rastreador, chame GoogleAnalyticsTracker.getInstance(). Em seguida, chame o método startNewSession dele, passando o ID da propriedade da Web e a atividade que está sendo acompanhada. Esse método pode ser chamado diretamente no método onCreate da sua atividade caso o app tenha apenas uma atividade. Exemplo:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

Se tiver várias atividades em seu aplicativo, você poderá usar a biblioteca EasyTracker fornecida na seção Downloads do projeto analytics-api-samples.

Acompanhamento de visualizações de página e eventos

O acompanhamento de exibições de página e eventos é simples: basta chamar trackPageView do objeto do rastreador sempre que você quiser acionar uma visualização de página. Chame trackEvent para gravar um evento. Para saber mais sobre visualizações de página e eventos, consulte a Visão geral do SDK acima.

Como usar variáveis personalizadas

Adicionar uma variável personalizada também é bem simples: basta usar o método setCustomVar fornecido pelo SDK para dispositivos móveis. Planeje com antecedência o qual indexa cada variável personalizada para que você não substitua nenhuma que já tenha sido criada. Para mais informações sobre variáveis personalizadas, consulte o Guia de variáveis personalizadas. Observe que o método setCustomVar não envia dados diretamente por conta própria. Em vez disso, os dados são enviados com o próximo evento ou visualização de página acompanhado. É necessário chamar setCustomVar antes de acompanhar uma visualização de página ou um evento. O escopo padrão das variáveis personalizadas é no escopo da página.

Como usar o acompanhamento de e-commerce

Existem quatro métodos para ativar o acompanhamento de e-commerce no seu aplicativo:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

Chamar addTransaction e addItem adiciona a transação ou o item a um buffer de e-commerce interno, em que mais itens e transações podem ser adicionados. Somente ao chamar trackTransactions, as transações e os itens são enviados ao agente e colocados na fila para serem enviados ao Google Analytics.

Para limpar o buffer, chame o método clearTransactions. Observação: o relatório não considera transações já enviadas ao agente nem transações já coletadas pelo Google Analytics.

O exemplo de código a seguir pode ajudar você a começar. Presumimos que o método onPurchaseCompleted é chamado quando a compra é confirmada ou negada. 

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

Para mais informações sobre comércio eletrônico, consulte o Guia de acompanhamento de comércio eletrônico.

Anonimizar IP

Para anonimizar as informações de IP do usuário, use o método setAnonymizeIp. Isso instrui o Google Analytics a anonimizar as informações enviadas pelo SDK removendo o último octeto do endereço IP antes que ele seja armazenado.

Você pode chamar setAnonymizeIp a qualquer momento.

Como definir a taxa de amostragem

Defina a taxa de amostragem usando o método setSampleRate. Se seu aplicativo gerar muito tráfego do Google Analytics, definir a taxa de amostragem pode impedir que seus relatórios sejam gerados usando dados de amostra. A amostragem ocorre de forma consistente entre usuários únicos, portanto, há integridade na tendência e nos relatórios quando a taxa de amostragem está ativada. O método setSampleRate aceita um parâmetro int. Os valores válidos para esse parâmetro são qualquer número inteiro entre 0 e 100, inclusive.

Uma taxa de 0 desativa a geração de hits, enquanto uma taxa de 100 envia todos os dados para o Google Analytics. É melhor chamar setSampleRate antes de chamar qualquer método de acompanhamento.

Saiba mais sobre amostragem no Guia de conceitos da amostragem.

Agrupar hits

Para reduzir a sobrecarga de conexão e bateria, recomendamos enviar suas solicitações de rastreamento em lotes. Você pode chamar dispatch no objeto de acompanhamento sempre que quiser fazer uma solicitação em lote, manualmente ou em intervalos de tempo específicos.

Problemas conhecidos

  • Chamar métodos GoogleAnalyticsTracker em conversas diferentes pode resultar em erros obscuros. Faça todas as chamadas na mesma linha de execução.

    • Acompanhamento de campanhas

    O SDK é compatível com dois tipos de acompanhamento de campanha.

    Acompanhamento de campanhas do Google Play: permite rastrear referências de instalação pelo Google Play.
    - Acompanhamento geral de campanhas: permite rastrear qualquer campanha que encaminha usuários ao seu aplicativo.

    Acompanhamento de campanhas do Google Play

    A versão do SO Android 1.6 é compatível com o uso de um parâmetro de URL referrer em links de download para o Google Play. O SDK do Google Analytics para Android usa esse parâmetro para preencher automaticamente as informações da campanha no Google Analytics para seu aplicativo. Isso permite que a origem da instalação do aplicativo seja registrada e associada a visualizações de página e eventos futuros, o que pode ser útil para avaliar a eficácia de um anúncio específico do seu aplicativo, por exemplo.

    Para que o rastreamento de referências funcione, adicione o seguinte snippet de código ao arquivo de manifesto AndroidManifest.xml do seu projeto:

    <!-- Used for install referrer tracking -->
<receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

    Para configurar o acompanhamento de campanhas do Google Analytics no Google Play, use o criador de URL abaixo para gerar um link de referência. Use o link para direcionar os usuários ao seu aplicativo. O SDK do Analytics analisa e registra automaticamente as informações de referência e as preenche no seu relatório do Analytics.

    Para gerar o link de referência, use o criador de URLs de campanhas do Google Play. Os campos Package Name, Campaign Source, Campaign Medium e Campaign Name são obrigatórios. Para uma descrição detalhada de cada parâmetro, consulte a tabela abaixo.

    Acompanhamento geral de campanhas

    Com a versão 1.3 do SDK do Google Analytics para Android, agora você pode acompanhar campanhas de origens diferentes do Google Play. Por exemplo, se você quer saber que seu aplicativo foi iniciado usando um link em um anúncio, confira as informações de referência da campanha na intenção que fez o aplicativo ser lançado e armazene essas informações no Google Analytics.

    Para definir as informações de referência da campanha, use o método setReferrer da seguinte maneira: 

      tracker.setReferrer(referrer);

    Há duas restrições ao uso desse recurso. Primeiro, chame startNewSession antes de setReferrer. Você precisa fazer isso porque o banco de dados SQLite usado pelo Google Analytics não está configurado antes de chamar startNewSession e setReferrer precisa desse banco de dados. Se você não chamou startNewSession, uma IllegalStateException será exibida.

    A segunda restrição é que a string de referência transmitida para setReferrer precisa seguir um formato específico. Ele precisa assumir a forma de um conjunto de parâmetros de URL e incluir pelo menos um parâmetro gclid ou utm_campaign, utm_medium e utm_source. No último caso, ela também pode ter os parâmetros utm_term e utm_content.

    O parâmetro gclid faz parte do recurso de codificação automática que vincula automaticamente o Google Analytics ao Google Ads. Este é um exemplo de referência de campanha que usa a codificação automática:

    referrer = “gclid=gclidValue”;

    A string de referência de campanha manual pode ter esta aparência:

    referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;

    Se você transmitir uma string de referenciador mal formada para setReferrer, as informações do referenciador não serão alteradas e você receberá um valor de retorno "false". Um valor de retorno "true" indica que o referenciador foi atualizado e será adicionado a cada hit daqui para frente.

    Uma nova sessão será iniciada quando você chamar setReferrer e ele retornar "true".

    Parâmetro Obrigatório Descrição Exemplos
    utm_campaign Sim Nome da campanha. Usado para a análise de palavras-chave a fim de identificar especificamente a promoção de um produto ou uma campanha estratégica utm_campaign=spring_sale
    utm_source Sim Origem da campanha. Usado para identificar um mecanismo de pesquisa, boletim informativo ou outra origem utm_source=google
    utm_medium Sim Mídia da campanha. Usado para identificar uma mídia, como e-mail ou custo por clique (CPC, na sigla em inglês) utm_medium=cpc
    utm_term Não Termo da campanha: usado com a pesquisa paga para fornecer as palavras-chave para os anúncios. utm_term=running+shoes
    utm_content Não Conteúdo da campanha. Usado para testes A/B e anúncios com segmentação por conteúdo para diferenciar anúncios ou links que direcionam ao mesmo URL utm_content=logolink
    utm_content=textlink