Configuração avançada

Este documento contém uma visão geral de alguns dos recursos de configuração avançada do SDK V4 do Google Analytics para Android.

Visão geral

O SDK do Google Analytics v4 para Android fornece uma classe Tracker para definir e enviar dados ao Google Analytics e um Singleton GoogleAnalytics que serve como uma interface para os valores de configuração globais da sua implementação.

Inicialização

Para que os dados sejam avaliados, você precisa inicializar pelo menos um rastreador por meio do singleton GoogleAnalytics fornecendo um objeto Context e um ID da propriedade do Google Analytics. Para ver detalhes, consulte a Referência do Google Analytics.

Uso de um arquivo de configuração

Também é possível inicializar um rastreador por meio de um arquivo de configuração. Exemplo:

package com.google.android.apps.mobileplayground;

import android.app.Application;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.Tracker;
import java.util.HashMap;

/**
 * An extension to Application class to provide tracker for analytics purposes. Having the tracker
 * instances here allows all the activities to access the same tracker instances. The trackers can
 * be initialised on startup or when they are required based on performance requirements.
 */
public class AnalyticsSampleApp extends Application {

  // The following line should be changed to include the correct property id.
  private static final String PROPERTY_ID = "UA-XXXXX-Y";

  /**
   * Enum used to identify the tracker that needs to be used for tracking.
   *
   * A single tracker is usually enough for most purposes. In case you do need multiple trackers,
   * storing them all in Application object helps ensure that they are created only once per
   * application instance.
   */
  public enum TrackerName {
    APP_TRACKER, // Tracker used only in this app.
    GLOBAL_TRACKER, // Tracker used by all the apps from a company. eg: roll-up tracking.
    ECOMMERCE_TRACKER, // Tracker used by all ecommerce transactions from a company.
  }

  HashMap<TrackerName, Tracker> mTrackers = new HashMap<TrackerName, Tracker>();

  public AnalyticsSampleApp() {
    super();
  }
  synchronized Tracker getTracker(TrackerName trackerId) {
    if (!mTrackers.containsKey(trackerId)) {

      GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);
      Tracker t = (trackerId == TrackerName.APP_TRACKER) ? analytics.newTracker(PROPERTY_ID)
          : (trackerId == TrackerName.GLOBAL_TRACKER) ? analytics.newTracker(R.xml.global_tracker)
              : analytics.newTracker(R.xml.ecommerce_tracker);
      mTrackers.put(trackerId, t);

    }
    return mTrackers.get(trackerId);
  }
}

Configuração e envio de dados

Os dados são enviados ao Google Analytics por meio de criadores para definir pares de valores de parâmetros que os enviam pelo método send do rastreador.

O exemplo a seguir mostra como enviar uma exibição de tela ao Google Analytics criando uma vista da propriedade do aplicativo e chamando o método de acompanhamento de envio:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

Sintaxe do "e" comercial do Protocolo de avaliação

Você pode usar a sintaxe do "e" comercial do Protocolo de avaliação para definir valores em um único hit com um HitBuilders.ScreenViewBuilder. Para definir valores em todos os hits subsequentes, use o próprio objeto de acompanhamento.

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(new HitBuilders.ScreenViewBuilder()
  .set("&cd", "Home Screen")
  .build()
);

Para ver a lista completa dos parâmetros do Protocolo de avaliação disponíveis, consulte a Referência de parâmetros do Protocolo de avaliação.

Aplicação de valores a vários hits

Todos os valores definidos diretamente no rastreador serão persistidos e aplicados a vários hits, como neste exemplo:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

// This event will also be sent with the most recently set screen name.
// Build and send an Event.
t.send(new HitBuilders.EventBuilder()
    .setCategory(getString(categoryId))
    .setAction(getString(actionId))
    .setLabel(getString(labelId))
    .build());

// Clear the screen name field when we're done.
t.setScreenName(null);

Somente os valores que você deseja persistir em vários hits devem ser definidos diretamente no rastreador. Convém definir um nome de tela em um rastreador, pois o mesmo valor pode ser aplicado a hits subsequentes de exibições de tela e eventos. No entanto, não é recomendado definir um campo como o tipo de hit no rastreador, pois ele provavelmente mudará a cada hit.

Uso de vários rastreadores

No seu aplicativo para dispositivos móveis, você pode usar vários rastreadores para enviar dados a propriedades diferentes:

public class MyApp extends Application {

  public void initTrackers() {
    GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);

    globalTracker = analytics.newTracker(R.xml.global_tracker);
    ecommerceTracker = analytics.newTracker(R.xml.ecommerce_tracker);
  }

  public static Tracker globalTracker;
  public static Tracker ecommerceTracker;

  ...
}

Embora seu aplicativo para dispositivos móveis possa ter vários rastreadores, você só pode usar um deles para informar exceções não identificadas chamando o método enableExceptionReporting() no rastreador.

Amostragem

Você pode ativar a amostragem do cliente para limitar o número de hits enviados ao Google Analytics. Se seu aplicativo tem um número grande de usuários ou envia um grande volume de dados ao Google Analytics, ativar a amostragem ajuda a garantir relatórios ininterruptos.

Por exemplo, para ativar a amostragem do cliente a uma taxa de 50%, use o parâmetro a seguir no seu arquivo de configuração:

<string name="ga_sampleFrequency">50.0</string>

Para ativar a amostragem do cliente de modo programático para um rastreador:

mTracker.setSampleRate(50.0d);

Para evitar inconsistências de relatórios, cada uma das vistas da propriedade (perfis) do seu aplicativo deve conter dados coletados com a mesma taxa de amostragem. Se versões diferentes do seu aplicativo usarem taxas de amostragem diferentes, você terá que configurar filtros da vista (perfil) usando a dimensão de versão do aplicativo para separar os dados de cada versão do seu aplicativo.

Desativação no nível do aplicativo

É possível ativar uma sinalização de desativação no nível do aplicativo que desativa o Google Analytics em todo o aplicativo. Essa sinalização precisa ser definida sempre que o aplicativo é iniciado e o padrão é false.

Para acessar a configuração de desativação no nível do aplicativo, use:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Para definir a desativação no nível do aplicativo, use:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

Em uma implementação típica, um app pode detectar uma mudança em SharedPreferences e atualizar a configuração de desativação do Google Analytics conforme necessário:

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
      // Any additional changed preference handling.
    }
  }
});

Excluir dados do usuário do lado do cliente

Se você precisar redefinir ou excluir dados do Google Analytics referentes aos seus usuários finais do lado do cliente, poderá excluir o arquivo Client-ID.

A exclusão do arquivo gaClientId forçará a geração de um novo Client-ID, que será usado por todos os hits subsequentes. Os dados anteriores não serão associados ao novo Client-ID.

Para excluir o arquivo gaClientId, use o método Context.deleteFile:

context.deleteFile("gaClientId");

Anonimizar IP

Ao ativar a funcionalidade anonimizar IP, você instrui o Google Analytics a anonimizar as informações de IP enviadas pelo SDK por meio da remoção do último octeto do endereço IP antes do armazenamento dele.

Para ativar a funcionalidade de anonimização de IP, use o parâmetro a seguir no seu arquivo de configuração:

<string name="ga_anonymizeIp">true</string>

Para ativar a funcionalidade de anonimização de IP de forma programática em um rastreador, use o método setAnonymizeIp:

mTracker.setAnonymizeIp(true)

O método setAnonymizeIp pode ser chamado a qualquer momento.

Como testar e depurar

O SDK do Google Analytics para Android fornece ferramentas para facilitar os testes e a depuração.

Dry Run

O SDK tem uma sinalização dryRun que, quando definida, impede que dados sejam enviados ao Google Analytics. A sinalização dryRun precisa ser definida sempre que você estiver testando ou depurando uma implementação e não quiser que os dados de teste apareçam nos relatórios do Google Analytics.

Para definir a sinalização "dry run":

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

Logger

O Google Analytics fará o registro no logcat com a tag GAv4 usando o sistema Log do Android. Por padrão, somente os níveis ERROR, WARN e INFO ficam ativados. Para ativar o nível DEBUG, execute o comando ADB a seguir no seu dispositivo ou emulador:

adb shell setprop log.tag.GAv4 DEBUG

Para ver somente mensagens do Google Analytics no logcat, use este comando:

adb logcat -v time -s GAv4

Para mais informações, consulte a Referência do logger do Google Analytics.