SDK do Google Analytics para Android v1 (legado)

O SDK do Google Analytics para apps para dispositivos móveis para Android facilita a implementação do Google Analytics em um aplicativo baseado no 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 usuários em sites tradicionais e interagir com widgets em páginas da Web tradicionais. Por esse motivo, os termos usados abaixo refletem o modelo convencional de acompanhamento de site e estão sendo mapeados para o acompanhamento de aplicativos para dispositivos móveis. Você precisa conhecer o acompanhamento do Analytics para entender como esse SDK funciona.

Use o SDK de acompanhamento de dispositivos móveis para acompanhar seus aplicativos para smartphones 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 de medir o volume de tráfego de um site tradicional. Como os apps para dispositivos móveis não contêm páginas HTML, é necessário decidir quando e com que frequência uma solicitação de visualização de página será acionada. Além disso, como as solicitações de visualização de página são criadas para gerar relatórios sobre as estruturas de diretórios, é necessário fornecer nomes descritivos para que as solicitações aproveitem a nomeação do caminho da página nos relatórios de conteúdo do Google Analytics. Os nomes escolhidos serão preenchidos nos seus relatórios do Google Analytics como caminhos de página, mesmo que não sejam páginas HTML, mas você pode usá-los a seu favor estruturando caminhos para oferecer outros agrupamentos às chamadas.
Acompanhamento de eventos
No Analytics, os eventos são projetados para rastrear a interação do usuário com elementos de páginas da Web de maneira diferente das solicitações de visualização de página. Você pode usar o recurso de acompanhamento de eventos do Google Analytics para fazer outras chamadas que serão informadas na seção "Acompanhamento de eventos" da interface de relatórios do Google Analytics. Os eventos são agrupados usando categorias e também podem usar rótulos por evento, o que oferece flexibilidade nos relatórios. Por exemplo, um app multimídia pode ter ações de reproduzir/parar/pausar para a categoria de vídeo e atribuir um rótulo para cada nome de vídeo. Os relatórios do Google Analytics agregariam eventos para todos os eventos marcados com a categoria video. Para mais informações sobre o acompanhamento de eventos, consulte o Guia de acompanhamento de eventos
Acompanhamento de e-commerce
Use o recurso de acompanhamento de e-commerce para rastrear transações do carrinho de compras e compras no app. Para rastrear 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 comércio eletrônico" da interface do Google Analytics. Para mais informações sobre o acompanhamento de e-commerce, consulte o guia de acompanhamento de e-commerce.
Variáveis personalizadas
As variáveis personalizadas são tags de par com valor e nome que você pode inserir no código de acompanhamento para refinar o acompanhamento do Google Analytics. Para mais informações sobre como você pode 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 aplicativo para Android, você precisará do seguinte:

Configuração

  • Adicionar 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" />

Um SDK de exemplo está incluído no SDK e demonstra como o projeto deve ser se a configuração for bem-sucedida. Fique à vontade para usá-lo como modelo para seus próprios aplicativos integrados ao Analytics.

Como usar o SDK

Antes de começar a usar o SDK, você precisa criar uma conta sem custo financeiro em www.google.com/analytics e criar uma nova propriedade da Web nessa conta usando um URL de site falso, mas descritivo, (por exemplo, http://mymobileapp.mywebsite.com). Depois de criar a propriedade, anote ou mantenha uma cópia do ID de 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 se reserva o direito de acompanhar e informar anonimamente a atividade de um usuário no seu 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 se inscrever em uma conta.

Exemplos e práticas recomendadas

Veja o exemplo de código e as práticas recomendadas em code.google.com no projeto analytics-api-samples.

Biblioteca EasyTracker

Uma biblioteca do EasyTracker está disponível. Ele oferece rastreamento em nível de aplicativo e atividade com quase nenhum esforço de desenvolvimento. Ele pode ser encontrado na seção Downloads do projeto analytics-api-samples.

Como iniciar o tracker

Para acessar o singleton do rastreador, chame GoogleAnalyticsTracker.getInstance(). Em seguida, chame o método startNewSession, transmitindo o ID da propriedade da Web e a atividade que estão sendo rastreadas. Você pode chamar esse método diretamente no método onCreate da sua atividade se o aplicativo tiver 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 você tiver várias atividades no aplicativo, use 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 visualizaçõ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 Visão geral do SDK acima.

Como usar variáveis personalizadas

Adicionar uma variável personalizada também é simples: basta usar o método setCustomVar fornecido pelo SDK para dispositivos móveis. Planeje com antecedência para que cada índice personalizado será mapeado, de modo que você não substitua nenhuma variável existente anteriormente. Para mais informações sobre variáveis personalizadas, consulte o Guia de variáveis personalizadas. O método setCustomVar não envia dados diretamente. Em vez disso, os dados são enviados com a próxima visualização de página ou evento rastreado. É necessário chamar setCustomVar antes de acompanhar uma visualização de página ou um evento. O escopo padrão das variáveis personalizadas está no escopo da página.

Como usar o acompanhamento de e-commerce

Você pode usar quatro métodos para ativar o acompanhamento de e-commerce em 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. Apenas ao chamar trackTransactions, as transações e os itens serã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: ele não se lembra de nenhuma transação enviada anteriormente ao agente nem de transações já coletadas pelo Google Analytics.

A amostra 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 informa ao Google Analytics para anonimizar as informações enviadas pelo SDK removendo o último octeto do endereço IP antes que ele seja armazenado.

Você pode chamar o setAnonymizeIp a qualquer momento.

Como definir a taxa de amostragem

É possível definir a taxa de amostragem usando o método setSampleRate. Se o seu aplicativo gerar muito tráfego do Analytics, a definição da taxa de amostragem poderá impedir que seus relatórios sejam gerados com dados de amostra. A amostragem ocorre de forma consistente em usuários únicos. Sendo assim, há integridade na tendência e na geração de 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 0 desativa a geração de hits, enquanto uma taxa 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.

Hits em lote

Para economizar energia e sobrecarga da conexão, recomendamos agrupar as solicitações de acompanhamento em lotes. Você pode chamar dispatch no objeto de acompanhamento sempre que quiser fazer uma solicitação em lote e fazer isso manualmente ou em intervalos de tempo específicos.

Problemas conhecidos

  • Chamar métodos do GoogleAnalyticsTracker em conversas diferentes pode resultar em erros obscuros. Faça todas as chamadas na mesma conversa.

    • Acompanhamento de campanhas

    O SDK aceita dois tipos de acompanhamento de campanha.

    - Acompanhamento de campanhas do Google Play: permite rastrear referências de instalação pelo Google Play.
    - Acompanhamento geral da campanha: permite acompanhar qualquer campanha que encaminha os 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 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 no seu app, por exemplo.

    Para que o rastreamento de referência 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 analisará e registrará automaticamente as informações de referência e as preencherá no seu relatório do Google Analytics.

    Para gerar o link de referência, use o criador de URLs de campanhas do Google Play. Os atributos Nome do pacote, Origem da campanha, Mídia da campanha e Nome da campanha são obrigatórios. Para uma descrição detalhada de cada parâmetro, consulte a tabela abaixo.

    Acompanhamento geral da campanha

    Com a versão 1.3 do SDK do Google Analytics para Android, agora você pode acompanhar campanhas de origens que não sejam o Google Play. Por exemplo, para saber se seu aplicativo foi iniciado por um link em um anúncio, verifique as informações de referência da campanha na intent que causou o lançamento do aplicativo e armazene-as 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 para o uso desse recurso. Primeiro, chame startNewSession antes de chamar 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, receberá um IllegalStateException.

    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 um de cada, 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. Um exemplo de referência de campanha usando a codificação automática pode ter a seguinte aparência:

    referrer = “gclid=gclidValue”;

    A string de referência da campanha manual pode ser semelhante a esta:

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

    Se você passar 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 falso. Um valor de retorno "true" indica que o referenciador foi atualizado e será adicionado a cada hit no futuro.

    Além disso, uma nova sessão será iniciada quando você chamar setReferrer e ela 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